rails-hyperdrive-layered-rails 0.1.0

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/complex-input-to-form-object.md

@@ -0,0 +1,119 @@
+# Form Object for Complex Input
+
+Replace a controller orchestrating multiple models with a form object that owns the registration workflow.
+
+## Contents
+
+- Before (fat controller)
+- After (form object)
+
+## Before
+
+```ruby
+class RegistrationsController < ApplicationController
+  def create
+    @user = User.new(user_params)
+    @user.profile = Profile.new(profile_params)
+
+    if @user.email.end_with?("@company.com")
+      @user.role = :employee
+      @user.team = Team.find_by(department: profile_params[:department])
+    end
+
+    if @user.save
+      UserMailer.welcome(@user).deliver_later
+      redirect_to dashboard_path
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:email, :password, :name)
+  end
+
+  def profile_params
+    params.require(:profile).permit(:bio, :department, :avatar)
+  end
+end
+```
+
+## After
+
+```ruby
+# app/forms/registration_form.rb
+class RegistrationForm < ApplicationForm
+  attribute :email, :string
+  attribute :password, :string
+  attribute :name, :string
+  attribute :bio, :string
+  attribute :department, :string
+  attribute :avatar
+
+  validates :email, :password, :name, presence: true
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :password, length: { minimum: 8 }
+
+  def save
+    return false unless valid?
+
+    ApplicationRecord.transaction do
+      create_user
+      create_profile
+      assign_team if company_email?
+    end
+
+    true
+  rescue ActiveRecord::RecordInvalid => e
+    errors.merge!(e.record.errors)
+    false
+  end
+
+  attr_reader :user
+
+  private
+
+  def create_user
+    @user = User.create!(
+      email: email,
+      password: password,
+      name: name,
+      role: company_email? ? :employee : :member
+    )
+  end
+
+  def create_profile
+    @user.create_profile!(bio: bio, department: department, avatar: avatar)
+  end
+
+  def assign_team
+    @user.update!(team: Team.find_by(department: department))
+  end
+
+  def company_email?
+    email.end_with?("@company.com")
+  end
+end
+
+# app/controllers/registrations_controller.rb
+class RegistrationsController < ApplicationController
+  def create
+    @form = RegistrationForm.new(registration_params)
+
+    if @form.save
+      UserMailer.welcome(@form.user).deliver_later
+      redirect_to dashboard_path
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def registration_params
+    params.require(:registration).permit(:email, :password, :name, :bio, :department, :avatar)
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/current-from-model.md

@@ -0,0 +1,63 @@
+# Extract Current from Model
+
+Remove `Current.user` access from a domain model by moving authorization to a policy and ownership to the controller.
+
+## Before
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :author, class_name: "User"
+
+  before_validation :set_author, on: :create
+
+  def can_edit?
+    author == Current.user || Current.user&.admin?
+  end
+
+  private
+
+  def set_author
+    self.author = Current.user
+  end
+end
+```
+
+## After
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  belongs_to :author, class_name: "User"
+  # No Current access - domain is context-agnostic
+end
+
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
+  def edit?
+    owner? || admin?
+  end
+
+  private
+
+  def owner?
+    record.author_id == user.id
+  end
+
+  def admin?
+    user.admin?
+  end
+end
+
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  def create
+    @post = current_user.posts.build(post_params)
+
+    if @post.save
+      redirect_to @post
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/god-object-decomposition.md

@@ -0,0 +1,81 @@
+# Extract God Object with Associated Objects
+
+Decompose a sprawling `User` model into focused collaborators using the associated-objects pattern.
+
+## Before
+
+```ruby
+class User < ApplicationRecord
+  # 500+ lines with multiple responsibilities
+
+  # Authentication
+  has_secure_password
+  def generate_token; end
+  def verify_token; end
+  def reset_password!; end
+
+  # Billing
+  def subscribe!(plan); end
+  def cancel_subscription!; end
+  def update_payment_method(token); end
+  def invoice_history; end
+
+  # Notifications
+  def notify!(message); end
+  def notification_preferences; end
+  def unread_notifications_count; end
+end
+```
+
+## After
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+
+  has_object :billing
+  has_object :notification_settings
+
+  # Only core user identity logic
+end
+
+# app/models/user/billing.rb
+class User::Billing
+  attr_reader :user
+
+  def initialize(user)
+    @user = user
+  end
+
+  def subscribe!(plan)
+    Stripe::Subscription.create(customer: stripe_customer_id, items: [{ price: plan.stripe_price_id }])
+    user.update!(plan: plan, subscribed_at: Time.current)
+  end
+
+  def cancel_subscription!
+    Stripe::Subscription.cancel(subscription_id)
+    user.update!(plan: nil, subscription_cancelled_at: Time.current)
+  end
+
+  def invoice_history
+    Stripe::Invoice.list(customer: stripe_customer_id)
+  end
+
+  private
+
+  def stripe_customer_id
+    user.stripe_customer_id
+  end
+end
+
+# app/models/user/notification_settings.rb
+class User::NotificationSettings
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :email_enabled, :boolean, default: true
+  attribute :push_enabled, :boolean, default: true
+  attribute :digest_frequency, :string, default: "daily"
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/implicit-to-explicit-state-machine.md

@@ -0,0 +1,77 @@
+# Replace Implicit State Machine
+
+Replace ad-hoc timestamp checks with an explicit state machine using the `workflow` gem.
+
+## Before
+
+```ruby
+class Order < ApplicationRecord
+  def status
+    return :cancelled if cancelled_at?
+    return :delivered if delivered_at?
+    return :shipped if shipped_at?
+    return :paid if paid_at?
+    :pending
+  end
+
+  def can_ship?
+    paid_at? && !shipped_at? && !cancelled_at?
+  end
+
+  def ship!
+    return false unless can_ship?
+    update!(shipped_at: Time.current)
+    OrderMailer.shipped(self).deliver_later
+  end
+end
+```
+
+## After
+
+```ruby
+# app/models/order.rb
+class Order < ApplicationRecord
+  include WorkflowActiverecord
+
+  workflow_column :status
+
+  workflow do
+    state :pending do
+      event :pay, transitions_to: :paid
+      event :cancel, transitions_to: :cancelled
+    end
+
+    state :paid do
+      event :ship, transitions_to: :shipped
+      event :cancel, transitions_to: :cancelled
+    end
+
+    state :shipped do
+      event :deliver, transitions_to: :delivered
+    end
+
+    state :delivered
+    state :cancelled
+  end
+
+  def ship
+    self.shipped_at = Time.current
+  end
+
+  def deliver
+    self.delivered_at = Time.current
+  end
+
+  def cancel
+    self.cancelled_at = Time.current
+  end
+end
+
+# Notifications in service
+class Orders::Ship < ApplicationService
+  def call(order)
+    order.ship!
+    OrderMailer.shipped(order).deliver_later
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/query-to-query-object.md

@@ -0,0 +1,63 @@
+# Extract Query Logic to Query Object
+
+Pull a long Active Record chain out of a controller into a composable query object.
+
+## Before
+
+```ruby
+class ReportsController < ApplicationController
+  def sales
+    @orders = Order
+      .joins(:customer, :line_items)
+      .where(status: :completed)
+      .where(created_at: params[:start_date]..params[:end_date])
+      .where(customers: { region: params[:region] }) if params[:region].present?
+      .group("DATE(orders.created_at)")
+      .select(
+        "DATE(orders.created_at) as date",
+        "COUNT(DISTINCT orders.id) as order_count",
+        "SUM(line_items.quantity * line_items.price) as revenue"
+      )
+      .order("date DESC")
+  end
+end
+```
+
+## After
+
+```ruby
+# app/queries/sales_report_query.rb
+class SalesReportQuery < ApplicationQuery
+  relation { Order.joins(:customer, :line_items).where(status: :completed) }
+
+  def by_date_range(start_date, end_date)
+    relation.where(created_at: start_date..end_date)
+  end
+
+  def by_region(region)
+    return relation if region.blank?
+    relation.where(customers: { region: region })
+  end
+
+  def daily_summary
+    relation
+      .group("DATE(orders.created_at)")
+      .select(
+        "DATE(orders.created_at) as date",
+        "COUNT(DISTINCT orders.id) as order_count",
+        "SUM(line_items.quantity * line_items.price) as revenue"
+      )
+      .order("date DESC")
+  end
+end
+
+# app/controllers/reports_controller.rb
+class ReportsController < ApplicationController
+  def sales
+    @orders = SalesReportQuery.new
+      .by_date_range(params[:start_date], params[:end_date])
+      .by_region(params[:region])
+      .daily_summary
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/examples/view-logic-to-presenter.md

@@ -0,0 +1,60 @@
+# Extract View Logic to Presenter
+
+Move complex view computations out of templates into a presenter wrapping the model.
+
+## Before
+
+```erb
+<%# app/views/users/show.html.erb %>
+<div class="profile">
+  <span class="badge <%= user.status == 'active' ? 'badge-success' : user.status == 'pending' ? 'badge-warning' : 'badge-secondary' %>">
+    <%= user.status.titleize %>
+  </span>
+
+  <h1>
+    <%= user.name.squish.split(/\s/).then { |parts| parts[0..-2].map { _1[0] + "." }.join + parts.last } %>
+  </h1>
+
+  <p>Member since <%= user.created_at.strftime("%B %Y") %></p>
+</div>
+```
+
+## After
+
+```ruby
+# app/presenters/user_presenter.rb
+class UserPresenter < SimpleDelegator
+  def status_badge_class
+    case status
+    when "active" then "badge-success"
+    when "pending" then "badge-warning"
+    else "badge-secondary"
+    end
+  end
+
+  def short_name
+    name.squish.split(/\s/).then do |parts|
+      parts[0..-2].map { _1[0] + "." }.join + parts.last
+    end
+  end
+
+  def member_since
+    created_at.strftime("%B %Y")
+  end
+end
+```
+
+```erb
+<%# app/views/users/show.html.erb %>
+<% present(@user) do |user| %>
+  <div class="profile">
+    <span class="badge <%= user.status_badge_class %>">
+      <%= user.status.titleize %>
+    </span>
+
+    <h1><%= user.short_name %></h1>
+
+    <p>Member since <%= user.member_since %></p>
+  </div>
+<% end %>
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/callbacks.md

@@ -0,0 +1,114 @@
+# Callback Anti-Patterns
+
+Misuses of Active Record callbacks that signal a layering problem.
+
+## Contents
+
+- Operation Callbacks
+- Skip Callback Anti-Pattern
+- Callback Control Flags
+
+## Operation Callbacks
+
+**Problem:** Business process steps disguised as callbacks.
+
+```ruby
+# BAD
+class User < ApplicationRecord
+  after_create :generate_initial_project, unless: :admin?
+  after_commit :send_welcome_email, on: :create
+  after_commit :sync_with_crm
+  after_commit :track_signup_analytics
+end
+```
+
+**Fix:** Extract to controller, service, or events.
+
+```ruby
+# GOOD - Controller handles side effects
+class UsersController < ApplicationController
+  def create
+    @user = User.create!(user_params)
+    UserMailer.welcome(@user).deliver_later
+    CrmSyncJob.perform_later(@user.id)
+    AnalyticsService.track_signup(@user)
+  end
+end
+
+# OR use events
+class User < ApplicationRecord
+  after_commit on: :create do
+    UserCreatedEvent.publish(user: self)
+  end
+end
+```
+
+## Skip Callback Anti-Pattern
+
+**Problem:** `skip_before_action` creates hidden dependencies.
+
+```ruby
+# BAD
+class ApplicationController < ActionController::Base
+  before_action :authenticate_user!
+  before_action :set_current_tenant
+end
+
+class PublicController < ApplicationController
+  skip_before_action :authenticate_user!
+  # Now depends on parent's internal callback order
+end
+```
+
+**Fix:** Use explicit inheritance or composition.
+
+```ruby
+# GOOD
+class AuthenticatedController < ApplicationController
+  before_action :authenticate_user!
+end
+
+class PublicController < ApplicationController
+  # No authentication needed
+end
+
+class DashboardController < AuthenticatedController
+  # Inherits authentication
+end
+```
+
+## Callback Control Flags
+
+**Problem:** Virtual attributes to skip callbacks.
+
+```ruby
+# BAD
+class User < ApplicationRecord
+  attr_accessor :skip_welcome_email, :skip_crm_sync
+
+  after_commit :send_welcome_email, unless: :skip_welcome_email
+  after_commit :sync_with_crm, unless: :skip_crm_sync
+end
+
+# Usage
+user = User.new(params)
+user.skip_welcome_email = true
+user.save!
+```
+
+**Fix:** Extract callbacks, call explicitly when needed.
+
+```ruby
+# GOOD
+class User < ApplicationRecord
+  # No operation callbacks
+end
+
+class RegisterUserService
+  def call(user_params, send_welcome: true)
+    user = User.create!(user_params)
+    UserMailer.welcome(user).deliver_later if send_welcome
+    user
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/concerns.md

@@ -0,0 +1,92 @@
+# Concern Anti-Patterns
+
+Misuses of `ActiveSupport::Concern` that hide structural problems.
+
+## Code-Slicing Concerns
+
+**Problem:** Splitting model by Rails artifact type, not behavior.
+
+```ruby
+# BAD - Just groups related code, not a behavior
+module Contactable
+  extend ActiveSupport::Concern
+
+  included do
+    validates :email, presence: true
+    validates :phone, format: { with: PHONE_REGEX }
+    before_save :normalize_phone
+  end
+
+  def full_contact_info
+    "#{email} / #{phone}"
+  end
+end
+```
+
+**Test:** If removing this concern breaks unrelated tests, it's code-slicing.
+
+**Fix:** Keep in model or extract to value object.
+
+```ruby
+# GOOD - Behavioral concern (can be tested in isolation)
+module Publishable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :published, -> { where.not(published_at: nil) }
+    scope :draft, -> { where(published_at: nil) }
+  end
+
+  def published? = published_at.present?
+
+  def publish!
+    update!(published_at: Time.current)
+  end
+end
+```
+
+## Overgrown Concerns
+
+**Problem:** Concern has too many responsibilities.
+
+```ruby
+# BAD - Too much in one concern
+module WithMedia
+  extend ActiveSupport::Concern
+
+  included do
+    has_many_attached :images
+    has_many_attached :videos
+    has_one_attached :thumbnail
+
+    after_commit :process_images
+    after_commit :generate_thumbnail
+    after_commit :transcode_videos
+  end
+
+  def images_ready? = # ...
+  def videos_ready? = # ...
+  def thumbnail_url = # ...
+  def processing_status = # ...
+  # 50 more methods...
+end
+```
+
+**Fix:** Extract to delegate object or separate concerns.
+
+```ruby
+# GOOD
+class Post::MediaProcessor
+  def initialize(post)
+    @post = post
+  end
+
+  def process_all
+    process_images
+    generate_thumbnail
+    transcode_videos
+  end
+
+  # ...
+end
+```