rails_console_pro 0.1.2 → 0.1.4

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Model introspection suite with callbacks, enums, concerns, scopes, validations, and method source lookup
+- Introspect command with filtered views and programmatic access
+- Comprehensive introspection documentation
+- Adaptive profiling command with SQL, cache, and duplicate query analysis
+- Profile result printer, serializer, and documentation
+
 ## [0.1.0] - 2025-01-XX
 
 ### Added

data/QUICK_START.md

@@ -59,6 +59,21 @@ export schema(User) user_schema.json
 ```
 [Learn more →](docs/EXPORT.md)
 
+### Model Introspection
+```ruby
+introspect User
+introspect User, :callbacks
+introspect User, :enums
+```
+[Learn more →](docs/MODEL_INTROSPECTION.md)
+
+### Snippet Library
+```ruby
+snippets(:add, "User.where(active: true).count", description: "Active users", tags: %w[users metrics])
+snippets(:list)
+```
+[Learn more →](docs/SNIPPETS.md)
+
 ### Beautiful Formatting
 ```ruby
 User.first  # Automatically formatted with colors
@@ -101,8 +116,10 @@ rails generate rails_console_pro:install
 - [SQL Explain](docs/SQL_EXPLAIN.md)
 - [Model Statistics](docs/MODEL_STATISTICS.md)
 - [Association Navigation](docs/ASSOCIATION_NAVIGATION.md)
+- [Model Introspection](docs/MODEL_INTROSPECTION.md)
 - [Object Diffing](docs/OBJECT_DIFFING.md)
 - [Export](docs/EXPORT.md)
+- [Snippets](docs/SNIPPETS.md)
 - [Formatting](docs/FORMATTING.md)
 
 ## Need Help?

data/README.md

@@ -14,9 +14,15 @@ Rails Console Pro transforms your Rails console into a powerful debugging enviro
 - 🔍 **SQL Explain** - Analyze query execution plans with performance recommendations
 - 🧭 **Association Navigator** - Interactive navigation through model associations
 - 📈 **Model Statistics** - Record counts, growth rates, table sizes, and index usage
+- 🔬 **Adaptive Profiling** - Profile blocks or relations with query, cache, and performance metrics
+- 🧵 **ActiveJob Insights** - Inspect and manage queues across adapters (Sidekiq, SolidQueue, Test, Async) with filters and inline actions
 - 🔄 **Object Diffing** - Compare ActiveRecord objects and highlight differences
+- 🔍 **Model Introspection** - Deep dive into callbacks, enums, concerns, scopes, validations, and method sources
+- ⚖️ **Query Comparison** - Compare multiple query strategies side-by-side to find optimal approaches
+- 🔧 **Query Builder** - Interactive DSL for building and analyzing ActiveRecord queries
 - 💾 **Export Capabilities** - Export to JSON, YAML, and HTML formats
 - 📄 **Smart Pagination** - Automatic pagination for large collections
+- 📝 **Snippet Library** - Capture, search, and reuse console snippets across sessions
 
 ## 🚀 Installation
 
@@ -62,6 +68,35 @@ diff user1, user2
 
 # Export
 export schema(User) user_schema.json
+
+# Profiling
+profile('Load users') { User.active.includes(:posts).limit(10).to_a }
+
+# Queue insights
+jobs(limit: 10, queue: 'mailers')
+jobs status=retry class=ReminderJob
+jobs retry=abcdef123456
+jobs details=abcdef123456
+
+# Model introspection
+introspect User
+introspect User, :callbacks
+introspect User, :enums
+introspect User, :method_name  # Find where method is defined
+
+# Query comparison
+compare do |c|
+  c.run("Eager loading") { User.includes(:posts).to_a }
+  c.run("N+1") { User.all.map(&:posts) }
+end
+
+# Query builder
+query User do
+  where(active: true)
+  includes(:posts)
+  order(:created_at)
+  limit(10)
+end.analyze  # Shows SQL + explain
 ```
 
 See [QUICK_START.md](QUICK_START.md) for more examples and detailed documentation for each feature.
@@ -78,6 +113,9 @@ RailsConsolePro.configure do |config|
   config.schema_command_enabled = true
   config.explain_command_enabled = true
   config.stats_command_enabled = true
+  config.queue_command_enabled = true
+  config.compare_command_enabled = true
+  config.query_builder_command_enabled = true
   
   # Color scheme
   config.color_scheme = :dark  # or :light
@@ -105,9 +143,14 @@ end
 - [SQL Explain](docs/SQL_EXPLAIN.md) - Analyze query performance
 - [Model Statistics](docs/MODEL_STATISTICS.md) - Get model statistics
 - [Association Navigation](docs/ASSOCIATION_NAVIGATION.md) - Navigate model associations
+- [Model Introspection](docs/MODEL_INTROSPECTION.md) - Deep dive into callbacks, enums, concerns, and more
 - [Object Diffing](docs/OBJECT_DIFFING.md) - Compare objects
 - [Export](docs/EXPORT.md) - Export to JSON, YAML, HTML
+- [Snippets](docs/SNIPPETS.md) - Build a reusable console snippet library
 - [Formatting](docs/FORMATTING.md) - Beautiful console output
+- [Adaptive Profiling](docs/PROFILING.md) - Measure queries, cache hits, and potential N+1 issues
+- [Queue Insights](docs/QUEUE_INSIGHTS.md) - Inspect jobs across ActiveJob adapters
+- [Query Builder & Comparator](docs/QUERY_BUILDER.md) - Compare query strategies and build optimized queries
 
 ## 🤝 Contributing
 

data/docs/FORMATTING.md

@@ -84,3 +84,8 @@ end
 - **Clean Layout**: Well-organized, readable output
 - **Dark/Light Themes**: Choose your preferred color scheme
 
+## Screenshots
+
+<img width="1117" height="551" alt="Screenshot 2025-11-07 at 11 42 52 AM" src="https://github.com/user-attachments/assets/2e77e0d5-8fa1-4249-8b0f-f8d16e829d99" />
+
+

data/docs/MODEL_INTROSPECTION.md

@@ -0,0 +1,371 @@
+# Model Introspection
+
+Deep dive into your ActiveRecord models with comprehensive introspection of callbacks, enums, concerns, scopes, validations, and lifecycle hooks.
+
+## Overview
+
+The `introspect` command provides a complete view of your model's internal structure, making it easy to understand complex models without digging through code files. Perfect for onboarding, debugging, and understanding model behavior.
+
+## Usage
+
+```ruby
+# Full introspection of a model
+introspect User
+
+# Get specific information
+introspect User, :callbacks        # Show only callbacks
+introspect User, :enums           # Show only enums
+introspect User, :concerns        # Show only concerns/modules
+introspect User, :scopes          # Show only scopes
+introspect User, :validations     # Show only validations
+
+# Find where a method is defined
+introspect User, :full_name
+```
+
+## Features
+
+### 1. Callbacks
+
+View all callbacks with their execution order, conditions, and types:
+
+```ruby
+introspect User, :callbacks
+```
+
+**Output includes:**
+- `before_validation`, `after_validation`
+- `before_save`, `around_save`, `after_save`
+- `before_create`, `around_create`, `after_create`
+- `before_update`, `around_update`, `after_update`
+- `before_destroy`, `around_destroy`, `after_destroy`
+- `after_commit`, `after_rollback`
+- `after_find`, `after_initialize`, `after_touch`
+- Conditional callbacks (`:if`, `:unless`)
+
+### 2. Enums
+
+See all enum definitions with their mappings and types:
+
+```ruby
+introspect User, :enums
+```
+
+**Shows:**
+- Enum name and values
+- Type (integer or string)
+- Value mappings
+- All possible states
+
+### 3. Concerns & Modules
+
+Discover all included modules and concerns:
+
+```ruby
+introspect User, :concerns
+```
+
+**Displays:**
+- All concerns included in the model
+- Parent classes in inheritance chain
+- Modules mixed in
+- Source file locations
+- Whether it's a concern, class, or module
+
+### 4. Scopes
+
+View all scopes with their SQL:
+
+```ruby
+introspect User, :scopes
+```
+
+**Provides:**
+- Scope name
+- Generated SQL
+- Scope conditions and values
+- WHERE, ORDER, LIMIT, INCLUDES clauses
+
+### 5. Validations
+
+Comprehensive validation information:
+
+```ruby
+introspect User, :validations
+```
+
+**Includes:**
+- Validation type (presence, uniqueness, length, etc.)
+- Attributes being validated
+- Options (allow_nil, allow_blank, etc.)
+- Conditions (if, unless)
+- Validator-specific options
+
+### 6. Method Source Location
+
+Find where any method is defined:
+
+```ruby
+introspect User, :full_name
+```
+
+**Returns:**
+- File path
+- Line number
+- Owner class/module
+- Type (model, concern, gem, parent)
+
+## Full Introspection Example
+
+```ruby
+introspect User
+```
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════════════
+🔍 MODEL INTROSPECTION: User
+═══════════════════════════════════════════════════════════
+
+📊 Lifecycle Summary:
+  Callbacks: 12
+  Validations: 8
+  ✓ Has state machine
+
+🔔 Callbacks:
+
+  before_validation (2):
+    1. normalize_email (if: :email_changed?)
+    2. strip_whitespace
+
+  after_create (3):
+    1. send_welcome_email
+    2. create_default_profile
+    3. track_signup
+
+  after_commit (1):
+    1. flush_cache
+
+✅ Validations:
+
+  email:
+    - PresenceValidator
+    - UniquenessValidator (case_sensitive: false)
+    - FormatValidator (with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+
+  password:
+    - PresenceValidator (on: :create)
+    - LengthValidator (minimum: 8)
+
+🔢 Enums:
+
+  status [Integer]:
+    active, inactive, suspended, deleted
+    Mapping: active => 0, inactive => 1, suspended => 2, deleted => 3
+
+  role [String]:
+    user, admin, moderator
+
+🔭 Scopes:
+
+  active:
+    └─ SQL: SELECT "users".* FROM "users" WHERE "users"."status" = 0
+    └─ where: status = 0
+
+  recent:
+    └─ SQL: SELECT "users".* FROM "users" ORDER BY "users"."created_at" DESC LIMIT 10
+    └─ order: created_at DESC
+    └─ limit: 10
+
+📦 Concerns & Modules:
+
+  Concerns:
+    ● Authenticatable app/models/concerns/authenticatable.rb:3
+    ● Trackable app/models/concerns/trackable.rb:1
+
+  Classes:
+    ▪ ApplicationRecord app/models/application_record.rb:1
+
+═══════════════════════════════════════════════════════════
+Generated: 2025-11-13 10:30:45
+
+💡 Tip: Use introspect User, :callbacks to see only callbacks
+       Use introspect User, :method_name to find where a method is defined
+```
+
+## Export Results
+
+Export introspection data to various formats:
+
+```ruby
+result = introspect User
+
+# Export to JSON
+result.to_json
+result.to_json(pretty: true)
+
+# Export to YAML
+result.to_yaml
+
+# Export to HTML
+result.to_html
+
+# Export to file
+result.export_to_file('user_introspection.json')
+result.export_to_file('user_introspection.html', format: :html)
+
+# Or use the export command
+export introspect(User), 'user_introspection.json'
+```
+
+## Programmatic Access
+
+Access introspection data programmatically:
+
+```ruby
+result = introspect User
+
+# Check what's available
+result.has_callbacks?    # => true
+result.has_enums?        # => true
+result.has_concerns?     # => true
+result.has_scopes?       # => true
+result.has_validations?  # => true
+
+# Get specific data
+result.callbacks_by_type(:before_save)
+result.validations_for(:email)
+result.enum_values(:status)
+result.scope_sql(:active)
+
+# Find method source
+result.method_source(:full_name)
+# => { file: "app/models/user.rb", line: 42, owner: "User", type: :model }
+```
+
+## Use Cases
+
+### 1. **Onboarding New Developers**
+```ruby
+# Quickly understand a complex model
+introspect Order
+```
+
+### 2. **Debugging Callback Issues**
+```ruby
+# See callback execution order
+introspect User, :callbacks
+```
+
+### 3. **Understanding State Machines**
+```ruby
+# View all enum states
+introspect Order, :enums
+```
+
+### 4. **Audit Model Structure**
+```ruby
+# Check what validations are in place
+introspect User, :validations
+```
+
+### 5. **Finding Method Definitions**
+```ruby
+# Where is this method coming from?
+introspect User, :authenticate
+# Shows if it's in the model, a concern, or a gem
+```
+
+### 6. **Scope Analysis**
+```ruby
+# See what SQL a scope generates
+introspect Product, :scopes
+```
+
+## Edge Cases Handled
+
+The introspection system handles:
+- **Abstract classes** - Validates model is not abstract
+- **Missing tables** - Checks table existence
+- **STI models** - Works with Single Table Inheritance
+- **Polymorphic associations** - Handles correctly
+- **Proc callbacks** - Shows as `<Proc>`
+- **Conditional validations** - Displays if/unless conditions
+- **State machine gems** - Detects AASM, StateMachines, Workflow
+- **Namespaced models** - Works with module namespaces
+- **Complex inheritance** - Shows full ancestry chain
+
+## Configuration
+
+Enable/disable the introspect command:
+
+```ruby
+# config/initializers/rails_console_pro.rb
+RailsConsolePro.configure do |config|
+  config.introspect_command_enabled = true  # default
+end
+```
+
+## Tips & Best Practices
+
+1. **Start with full introspection** - Get the complete picture first
+2. **Use filters for focused analysis** - Add `:callbacks`, `:enums`, etc. when you know what you need
+3. **Export for documentation** - Generate HTML reports for team reference
+4. **Method source is powerful** - Use it to track down mysterious behavior
+5. **Combine with other commands** - Use `schema` for database structure, `introspect` for Ruby logic
+
+## Limitations
+
+- Callbacks that are added dynamically at runtime may not appear
+- Private methods in concerns may not have accurate source locations
+- Some gems that modify ActiveRecord may interfere with introspection
+- Very large models (100+ callbacks) may take a moment to process
+
+## Related Commands
+
+- `schema Model` - Database schema and structure
+- `stats Model` - Model statistics and metrics
+- `diff obj1, obj2` - Compare two instances
+- `explain Query` - SQL query analysis
+
+## Troubleshooting
+
+**Q: Why don't I see any callbacks?**
+A: Ensure your model has callbacks defined. Abstract classes and tableless models may not have callbacks.
+
+**Q: Method source shows nil**
+A: Some methods (built-in Rails methods, dynamically defined) don't have accessible source locations.
+
+**Q: Scopes appear empty**
+A: Only scopes that don't require arguments are shown. Parameterized scopes are skipped.
+
+**Q: Concerns are missing**
+A: Only concerns/modules with identifiable names are shown. Anonymous modules are excluded.
+
+## Examples
+
+### Simple Model
+```ruby
+introspect BlogPost
+# Shows validations, scopes, associations
+```
+
+### Complex Model with State Machine
+```ruby
+introspect Order
+# Shows state machine enums, callbacks, validations
+```
+
+### Finding Gem Methods
+```ruby
+introspect User, :authenticate
+# Shows it comes from Devise gem
+```
+
+### Debugging Callback Order
+```ruby
+introspect Payment, :callbacks
+# See exact order of before_save, after_commit, etc.
+```
+

data/docs/MODEL_STATISTICS.md

@@ -70,3 +70,7 @@ export stats(User) user_stats.json
 - **Index Usage**: Which indexes are used frequently
 - **Column Statistics**: Unique values, distributions, ranges (for smaller tables)
 
+## Screenshots
+
+<img width="1119" height="714" alt="Screenshot 2025-11-07 at 11 44 01 AM" src="https://github.com/user-attachments/assets/a175cb8c-1bea-4819-a80b-3f0bbb0d1a75" />
+

data/docs/OBJECT_DIFFING.md

@@ -85,3 +85,9 @@ diff(user1, user2).to_json
 - **Multiple Object Types**: Works with ActiveRecord, Hash, and more
 - **Export Support**: Export diff results to JSON/YAML/HTML
 
+## Screenshots
+
+<img width="1057" height="650" alt="Screenshot 2025-11-07 at 11 27 23 AM" src="https://github.com/user-attachments/assets/ca9fce82-8ed8-4506-907b-75e07735ec66" />
+
+
+

data/docs/PROFILING.md

@@ -0,0 +1,91 @@
+# Adaptive Profiling
+
+Rails Console Pro includes an adaptive profiler that wraps any block, callable, or ActiveRecord relation and reports real-time performance metrics without leaving the console.
+
+## Why Use It?
+
+- Understand how long a console experiment takes end-to-end
+- See how much time is spent inside SQL queries
+- Detect cache hits/misses and duplicated queries (potential N+1s)
+- Keep a sample of executed SQL statements with bind values
+- Capture errors while still getting timing information
+
+## Basic Usage
+
+```ruby
+# Profile a block
+profile { User.active.limit(25).to_a }
+
+# Add a label for the session
+profile('Load active users') { User.active.includes(:posts).limit(25).to_a }
+
+# Profile a relation (loads it automatically)
+relation = User.includes(:posts).limit(10)
+profile relation
+
+# Profile any callable object
+profile -> { HeavyService.call(user) }
+```
+
+`profile` returns a `RailsConsolePro::ProfileResult` instance, so you can further inspect or export the collected metrics.
+
+## Sample Output
+
+```
+🧪 PROFILE: Load active users
+⏱ Execution Summary:
+  Total time        35.42 ms
+  SQL time          28.12 ms
+    (79.36% of total time spent in SQL)
+
+🗂 Query Breakdown:
+  Total queries     4
+  Read queries      4
+  Write queries     0
+  Cached queries    1
+
+🐢 Slow Queries (100.0ms+):
+  1. 120.44 ms SELECT "users".* FROM ...
+```
+
+The printer also highlights cache activity, sample queries, potential N+1 issues, and any error raised during execution.
+
+## Configuration
+
+Tune profiling behaviour via the initializer:
+
+```ruby
+RailsConsolePro.configure do |config|
+  # Enable/disable the profile command
+  config.profile_command_enabled = true
+
+  # Flag queries above this threshold (milliseconds)
+  config.profile_slow_query_threshold = 120.0
+
+  # Minimum occurrences before a query is treated as a possible N+1
+  config.profile_duplicate_query_threshold = 3
+
+  # Number of query samples to keep in memory for reporting
+  config.profile_max_saved_queries = 10
+end
+```
+
+## Exporting
+
+Profile results can be exported like any other value object:
+
+```ruby
+result = profile { User.active.limit(10).to_a }
+
+result.to_json
+result.to_yaml
+result.export_to_file('profile.html', format: :html)
+```
+
+## Tips
+
+- Combine profiling with Rails scopes to analyse real data paths
+- Lower `profile_slow_query_threshold` when testing on local databases
+- Use labels to differentiate multiple runs in the same console session
+- Errors are captured and displayed; you still get timings even when the block fails
+