whodunit 0.1.0

data/lib/whodunit/current.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Thread-safe current user context using Rails CurrentAttributes.
+  #
+  # This class provides a thread-safe way to store the current user for auditing purposes.
+  # It leverages Rails' CurrentAttributes functionality to ensure proper isolation
+  # across threads and requests.
+  #
+  # @example Setting a user
+  #   Whodunit::Current.user = User.find(123)
+  #   Whodunit::Current.user = 123  # Can also set by ID directly
+  #
+  # @example Getting the user ID
+  #   Whodunit::Current.user_id  # => 123
+  #
+  # @example In a controller
+  #   class ApplicationController < ActionController::Base
+  #     before_action :set_current_user
+  #
+  #     private
+  #
+  #     def set_current_user
+  #       Whodunit::Current.user = current_user
+  #     end
+  #   end
+  #
+  # @since 0.1.0
+  class Current < ActiveSupport::CurrentAttributes
+    # @!attribute [rw] user
+    #   @return [Integer, nil] the current user ID
+    attribute :user
+
+    class << self
+      # Store the original user= method before we override it
+      alias original_user_assignment user=
+
+      # Set the current user by object or ID.
+      #
+      # Accepts either a user object (responds to #id) or a user ID directly.
+      # The user ID is stored for database operations.
+      #
+      # @param user [Object, Integer, nil] user object or user ID
+      # @return [Integer, nil] the stored user ID
+      # @example
+      #   Whodunit::Current.user = User.find(123)
+      #   Whodunit::Current.user = 123
+      #   Whodunit::Current.user = nil  # Clear current user
+      def user=(user)
+        value = user.respond_to?(:id) ? user.id : user
+        original_user_assignment(value)
+      end
+
+      # Override reset to ensure our custom setter is preserved
+      def reset
+        super
+        # Redefine our custom setter after reset
+        _redefine_user_setter
+      end
+
+      private
+
+      def _redefine_user_setter
+        # Nothing needed here since we're using original_user_assignment
+      end
+    end
+
+    # Get the current user ID for database storage.
+    #
+    # @return [Integer, nil] the current user ID
+    # @example
+    #   Whodunit::Current.user = User.find(123)
+    #   Whodunit::Current.user_id  # => 123
+    def self.user_id
+      user
+    end
+  end
+end

data/lib/whodunit/migration_helpers.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Database migration helpers for adding whodunit stamp columns.
+  #
+  # This module provides convenient methods for adding creator/updater/deleter
+  # tracking columns to database tables. It intelligently detects soft-delete
+  # implementations and adds appropriate indexes for performance.
+  #
+  # @example Add stamps to existing table
+  #   class AddWhodunitStampsToPosts < ActiveRecord::Migration[7.0]
+  #     def change
+  #       add_whodunit_stamps :posts
+  #       # Adds creator_id, updater_id columns
+  #       # Adds deleter_id if soft-delete detected
+  #     end
+  #   end
+  #
+  # @example Add stamps to new table
+  #   class CreatePosts < ActiveRecord::Migration[7.0]
+  #     def change
+  #       create_table :posts do |t|
+  #         t.string :title
+  #         t.text :body
+  #         t.whodunit_stamps
+  #         t.timestamps
+  #       end
+  #     end
+  #   end
+  #
+  # @example Custom data types
+  #   add_whodunit_stamps :posts,
+  #     creator_type: :string,
+  #     updater_type: :uuid,
+  #     include_deleter: true
+  #
+  # @since 0.1.0
+  module MigrationHelpers
+    # Add creator/updater stamp columns to an existing table.
+    #
+    # This method adds the configured creator and updater columns to an existing table.
+    # It optionally adds a deleter column based on soft-delete detection or explicit configuration.
+    # Indexes are automatically added for performance.
+    #
+    # @param table_name [Symbol] the table to add stamps to
+    # @param include_deleter [Symbol, Boolean] :auto to auto-detect soft-delete,
+    #   true to force inclusion, false to exclude
+    # @param creator_type [Symbol, nil] data type for creator column (defaults to configured type)
+    # @param updater_type [Symbol, nil] data type for updater column (defaults to configured type)
+    # @param deleter_type [Symbol, nil] data type for deleter column (defaults to configured type)
+    # @return [void]
+    # @example Basic usage
+    #   add_whodunit_stamps :posts
+    # @example With custom types
+    #   add_whodunit_stamps :posts, creator_type: :string, updater_type: :uuid
+    # @example Force deleter column
+    #   add_whodunit_stamps :posts, include_deleter: true
+    def add_whodunit_stamps(table_name, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil)
+      add_column table_name, Whodunit.creator_column, creator_type || Whodunit.creator_data_type, null: true
+      add_column table_name, Whodunit.updater_column, updater_type || Whodunit.updater_data_type, null: true
+
+      if should_include_deleter?(table_name, include_deleter)
+        add_column table_name, Whodunit.deleter_column, deleter_type || Whodunit.deleter_data_type, null: true
+      end
+
+      add_whodunit_indexes(table_name, include_deleter)
+    end
+
+    # Remove stamp columns from an existing table.
+    #
+    # This method removes the configured creator, updater, and optionally deleter
+    # columns from an existing table. Only removes columns that actually exist.
+    #
+    # @param table_name [Symbol] the table to remove stamps from
+    # @param include_deleter [Symbol, Boolean] :auto to auto-detect soft-delete,
+    #   true to force removal, false to exclude
+    # @param _options [Hash] additional options (reserved for future use)
+    # @return [void]
+    # @example Basic usage
+    #   remove_whodunit_stamps :posts
+    # @example Force deleter removal
+    #   remove_whodunit_stamps :posts, include_deleter: true
+    def remove_whodunit_stamps(table_name, include_deleter: :auto, **_options)
+      remove_column table_name, Whodunit.creator_column if column_exists?(table_name, Whodunit.creator_column)
+      remove_column table_name, Whodunit.updater_column if column_exists?(table_name, Whodunit.updater_column)
+
+      if should_include_deleter?(table_name, include_deleter) &&
+         column_exists?(table_name, Whodunit.deleter_column)
+        remove_column table_name, Whodunit.deleter_column
+      end
+    end
+
+    # Add stamp columns to a table definition or existing table.
+    #
+    # This method can be used in two ways:
+    # 1. Inside a create_table block (pass table definition as first argument)
+    # 2. As a standalone method in migrations (attempts to infer table name)
+    #
+    # @param table_def [ActiveRecord::ConnectionAdapters::TableDefinition, nil]
+    #   the table definition (when used in create_table block) or nil
+    # @param include_deleter [Symbol, Boolean] :auto to auto-detect soft-delete,
+    #   true to force inclusion, false to exclude
+    # @param creator_type [Symbol, nil] data type for creator column (defaults to configured type)
+    # @param updater_type [Symbol, nil] data type for updater column (defaults to configured type)
+    # @param deleter_type [Symbol, nil] data type for deleter column (defaults to configured type)
+    # @return [void]
+    # @example In create_table block
+    #   create_table :posts do |t|
+    #     t.string :title
+    #     t.whodunit_stamps
+    #   end
+    # @example Standalone (infers table from migration name)
+    #   def change
+    #     whodunit_stamps  # Adds to inferred table
+    #   end
+    def whodunit_stamps(table_def = nil, include_deleter: :auto, creator_type: nil, updater_type: nil,
+                        deleter_type: nil)
+      if table_def.nil?
+        handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type)
+      else
+        handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type)
+      end
+    end
+
+    private
+
+    # Handle stamps when called as migration method
+    def handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type)
+      table_name = infer_table_name_from_migration
+      return unless table_name
+
+      add_whodunit_stamps(table_name, include_deleter: include_deleter, creator_type: creator_type,
+                                      updater_type: updater_type, deleter_type: deleter_type)
+    end
+
+    # Handle stamps when called within create_table block
+    def handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type)
+      table_def.column Whodunit.creator_column, creator_type || Whodunit.creator_data_type, null: true
+      table_def.column Whodunit.updater_column, updater_type || Whodunit.updater_data_type, null: true
+
+      if should_include_deleter_for_new_table?(include_deleter)
+        table_def.column Whodunit.deleter_column, deleter_type || Whodunit.deleter_data_type, null: true
+      end
+
+      add_whodunit_indexes_for_create_table(table_def, include_deleter)
+    end
+
+    # Determine if deleter column should be included
+    def should_include_deleter?(table_name, include_deleter)
+      case include_deleter
+      when :auto
+        soft_delete_detected_for_table?(table_name)
+      when true
+        true
+      else
+        false
+      end
+    end
+
+    # For new tables, be more conservative with auto-detection
+    def should_include_deleter_for_new_table?(include_deleter)
+      case include_deleter
+      when true
+        true
+      else
+        false # Don't auto-add for new tables, let user be explicit
+      end
+    end
+
+    # Detect soft-delete patterns in existing table
+    def soft_delete_detected_for_table?(table_name)
+      return false unless table_exists?(table_name)
+
+      soft_delete_columns = %w[
+        deleted_at destroyed_at discarded_at archived_at
+        soft_deleted_at soft_destroyed_at removed_at
+      ]
+
+      soft_delete_columns.any? { |col| column_exists?(table_name, col) || column_exists?(table_name, col.to_sym) }
+    end
+
+    # Add indexes for performance
+    def add_whodunit_indexes(table_name, include_deleter)
+      add_index table_name, Whodunit.creator_column, name: "index_#{table_name}_on_creator"
+      add_index table_name, Whodunit.updater_column, name: "index_#{table_name}_on_updater"
+
+      return unless should_include_deleter?(table_name, include_deleter)
+
+      add_index table_name, Whodunit.deleter_column, name: "index_#{table_name}_on_deleter"
+    end
+
+    # Add indexes within create_table block
+    def add_whodunit_indexes_for_create_table(table_def, include_deleter)
+      # Skip indexes for table definitions that don't support them
+      return unless table_def.respond_to?(:index)
+
+      table_name = table_def.respond_to?(:name) ? table_def.name : "table"
+      table_def.index Whodunit.creator_column, name: "index_#{table_name}_on_creator"
+      table_def.index Whodunit.updater_column, name: "index_#{table_name}_on_updater"
+
+      return unless should_include_deleter_for_new_table?(include_deleter)
+
+      table_def.index Whodunit.deleter_column, name: "index_#{table_name}_on_deleter"
+    end
+
+    # Attempt to infer table name from migration class name
+    def infer_table_name_from_migration
+      return nil unless respond_to?(:migration_name)
+
+      # Extract table name from migration names like CreatePosts, AddStampsToPosts
+      case migration_name
+      when /^Create(\w+)$/
+        table_name = ::Regexp.last_match(1)
+        table_name.respond_to?(:underscore) ? table_name.underscore.pluralize : "#{table_name.downcase}s"
+      when /^Add\w*To(\w+)$/
+        table_name = ::Regexp.last_match(1)
+        table_name.respond_to?(:underscore) ? table_name.underscore : table_name.downcase
+      end
+    end
+
+    # Get migration name from class
+    def migration_name
+      self.class.name.demodulize
+    end
+  end
+end
+
+# Extend ActiveRecord::Migration when available
+ActiveRecord::Migration.include(Whodunit::MigrationHelpers) if defined?(ActiveRecord::Migration)

data/lib/whodunit/railtie.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Rails integration for automatic setup of Whodunit functionality.
+  #
+  # This Railtie automatically extends ActiveRecord migrations with MigrationHelpers
+  # and includes ControllerMethods in ActionController::Base when Rails is available.
+  # It provides seamless integration without requiring manual setup.
+  #
+  # @example Automatic integration (no setup required)
+  #   # In a Rails app, this automatically provides:
+  #   # - Migration helpers (add_whodunit_stamps, etc.)
+  #   # - Controller methods (set_whodunit_user, etc.)
+  #
+  # @note When Rails is not available, this class safely inherits from Object
+  #   and does not cause any errors.
+  #
+  # @since 0.1.0
+  class Railtie < (defined?(Rails::Railtie) ? Rails::Railtie : Object)
+    if defined?(Rails::Railtie)
+      railtie_name :whodunit
+
+      # Extend ActiveRecord with migration helpers.
+      #
+      # This initializer adds the MigrationHelpers module to ActiveRecord,
+      # making methods like add_whodunit_stamps available in migrations.
+      #
+      # @api private
+      initializer "whodunit.extend_active_record" do |_app|
+        ActiveSupport.on_load(:active_record) do
+          extend Whodunit::MigrationHelpers
+        end
+      end
+
+      # Include controller methods in ActionController::Base.
+      #
+      # This initializer adds the ControllerMethods module to ActionController::Base,
+      # making methods like set_whodunit_user and current_whodunit_user available
+      # in all controllers.
+      #
+      # @api private
+      initializer "whodunit.extend_action_controller" do |_app|
+        ActiveSupport.on_load(:action_controller_base) do
+          include Whodunit::ControllerMethods
+        end
+      end
+    end
+  end
+end

data/lib/whodunit/soft_delete_detector.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Smart detection of soft-delete implementations.
+  #
+  # This class provides multi-layered detection for various soft-delete implementations
+  # including popular gems like Discard and Paranoia, as well as custom implementations.
+  #
+  # @example Check if a model has soft-delete enabled
+  #   class Post < ApplicationRecord
+  #     # has deleted_at column
+  #   end
+  #
+  #   Whodunit::SoftDeleteDetector.enabled_for?(Post)  # => true
+  #
+  # @example With Discard gem
+  #   class Post < ApplicationRecord
+  #     include Discard::Model
+  #   end
+  #
+  #   Whodunit::SoftDeleteDetector.enabled_for?(Post)  # => true
+  #
+  # @since 0.1.0
+  class SoftDeleteDetector
+    # Main detection method that checks if soft-delete is enabled for a model.
+    #
+    # Uses multiple detection strategies:
+    # 1. Gem-based detection (Discard, Paranoia, etc.)
+    # 2. Column pattern detection (deleted_at, discarded_at, etc.)
+    # 3. Method-based detection (respond_to? soft-delete methods)
+    #
+    # @param model [Class] the ActiveRecord model class to check
+    # @return [Boolean] true if soft-delete is detected, false otherwise
+    # @example
+    #   Whodunit::SoftDeleteDetector.enabled_for?(Post)  # => true
+    #   Whodunit::SoftDeleteDetector.enabled_for?(User)  # => false
+    def self.enabled_for?(model)
+      return false unless model.respond_to?(:columns)
+
+      gem_based_detection?(model) ||
+        column_pattern_detection(model) ||
+        method_based_detection(model)
+    end
+
+    # Detect popular soft-delete gems.
+    #
+    # Detects the following gems:
+    # - Discard (checks for Discard module inclusion)
+    # - Paranoia (checks for paranoid? method and Paranoid ancestors)
+    # - ActsAsParanoid (checks for acts_as_paranoid method)
+    #
+    # @param model [Class] the ActiveRecord model class to check
+    # @return [Boolean] true if a gem-based soft-delete is detected
+    # @api private
+    def self.gem_based_detection?(model)
+      # Discard gem
+      return true if model.included_modules.any? { |mod| mod.to_s.include?("Discard") }
+
+      # Paranoia gem
+      return true if model.respond_to?(:paranoid?) ||
+                     model.respond_to?(:acts_as_paranoid) ||
+                     model.ancestors.any? { |a| a.to_s.include?("Paranoid") }
+
+      # ActsAsParanoid (older version)
+      return true if model.respond_to?(:acts_as_paranoid)
+
+      false
+    end
+
+    # Detect soft-delete by column patterns.
+    #
+    # Looks for common soft-delete column names:
+    # - deleted_at, destroyed_at, discarded_at, archived_at
+    # - soft_deleted_at, soft_destroyed_at, removed_at
+    #
+    # Only considers timestamp columns (datetime, timestamp, date).
+    #
+    # @param model [Class] the ActiveRecord model class to check
+    # @return [Boolean] true if soft-delete columns are found
+    # @api private
+    def self.column_pattern_detection(model)
+      soft_delete_columns = %w[
+        deleted_at destroyed_at discarded_at archived_at
+        soft_deleted_at soft_destroyed_at removed_at
+      ]
+
+      model.columns.any? do |column|
+        soft_delete_columns.include?(column.name) &&
+          timestamp_column?(column)
+      end
+    end
+
+    # Detect soft-delete by method presence.
+    #
+    # Checks if the model responds to common soft-delete method names.
+    # This catches custom implementations that follow standard naming conventions.
+    #
+    # @param model [Class] the ActiveRecord model class to check
+    # @return [Boolean] true if soft-delete methods are found
+    # @api private
+    def self.method_based_detection(model)
+      soft_delete_methods = %w[
+        deleted_at destroyed_at discarded_at archived_at
+        soft_deleted_at soft_destroyed_at removed_at
+      ]
+
+      soft_delete_methods.any? { |method| model.respond_to?(method) }
+    end
+
+    # Check if a column is a timestamp type.
+    #
+    # @param column [Object] the column object (responds to #type)
+    # @return [Boolean] true if the column is a timestamp type
+    # @api private
+    def self.timestamp_column?(column)
+      %i[datetime timestamp date].include?(column.type)
+    end
+  end
+end

data/lib/whodunit/stampable.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Main concern for adding creator/updater/deleter tracking to ActiveRecord models.
+  #
+  # This module provides automatic tracking of who created, updated, and deleted records.
+  # It intelligently sets up callbacks and associations based on available columns and
+  # soft-delete detection.
+  #
+  # @example Basic usage
+  #   class Post < ApplicationRecord
+  #     include Whodunit::Stampable
+  #   end
+  #
+  #   # Requires creator_id and/or updater_id columns
+  #   # Automatically adds deleter_id tracking if soft-delete is detected
+  #
+  # @example Migration
+  #   class CreatePosts < ActiveRecord::Migration[7.0]
+  #     def change
+  #       create_table :posts do |t|
+  #         t.string :title
+  #         t.text :body
+  #         t.whodunit_stamps  # Adds creator_id, updater_id columns
+  #         t.timestamps
+  #       end
+  #     end
+  #   end
+  #
+  # @example Manual deleter tracking
+  #   class Post < ApplicationRecord
+  #     include Whodunit::Stampable
+  #
+  #     # Force enable deleter tracking even without soft-delete
+  #     enable_whodunit_deleter!
+  #   end
+  #
+  # @since 0.1.0
+  module Stampable
+    extend ActiveSupport::Concern
+
+    included do
+      # Set up callbacks
+      before_create :set_whodunit_creator, if: :creator_column?
+      before_update :set_whodunit_updater, if: :updater_column?
+
+      # Only add destroy callback if soft-delete is detected
+      if Whodunit.auto_detect_soft_delete &&
+         Whodunit::SoftDeleteDetector.enabled_for?(self)
+        before_destroy :set_whodunit_deleter, if: :deleter_column?
+      end
+
+      # Set up associations - call on the class
+      setup_whodunit_associations
+    end
+
+    class_methods do # rubocop:disable Metrics/BlockLength
+      def soft_delete_enabled?
+        @soft_delete_enabled ||= Whodunit::SoftDeleteDetector.enabled_for?(self)
+      end
+
+      def enable_whodunit_deleter!
+        before_destroy :set_whodunit_deleter, if: :deleter_column?
+        setup_deleter_association
+        @soft_delete_enabled = true
+      end
+
+      def disable_whodunit_deleter!
+        skip_callback :destroy, :before, :set_whodunit_deleter
+        @soft_delete_enabled = false
+      end
+
+      private
+
+      def setup_whodunit_associations
+        setup_creator_association if creator_column_exists?
+        setup_updater_association if updater_column_exists?
+        setup_deleter_association if deleter_column_exists? && soft_delete_enabled?
+      end
+
+      def creator_column_exists?
+        column_names.include?(Whodunit.creator_column.to_s)
+      end
+
+      def updater_column_exists?
+        column_names.include?(Whodunit.updater_column.to_s)
+      end
+
+      def deleter_column_exists?
+        column_names.include?(Whodunit.deleter_column.to_s)
+      end
+
+      def setup_creator_association
+        belongs_to :creator,
+                   class_name: Whodunit.user_class_name,
+                   foreign_key: Whodunit.creator_column,
+                   optional: true
+      end
+
+      def setup_updater_association
+        belongs_to :updater,
+                   class_name: Whodunit.user_class_name,
+                   foreign_key: Whodunit.updater_column,
+                   optional: true
+      end
+
+      def setup_deleter_association
+        belongs_to :deleter,
+                   class_name: Whodunit.user_class_name,
+                   foreign_key: Whodunit.deleter_column,
+                   optional: true
+      end
+    end
+
+    # @!group Callback Methods
+
+    # Set the creator ID when a record is created.
+    #
+    # This method is automatically called before_create if the model has a creator column.
+    # It sets the creator_id to the current user from Whodunit::Current.
+    #
+    # @return [void]
+    # @api private
+    def set_whodunit_creator
+      return unless Whodunit::Current.user_id
+
+      self[Whodunit.creator_column] = Whodunit::Current.user_id
+    end
+
+    # Set the updater ID when a record is updated.
+    #
+    # This method is automatically called before_update if the model has an updater column.
+    # It sets the updater_id to the current user from Whodunit::Current.
+    # Does not run on new records (creation).
+    #
+    # @return [void]
+    # @api private
+    def set_whodunit_updater
+      return unless Whodunit::Current.user_id
+      return if new_record? # Don't set updater on creation
+
+      self[Whodunit.updater_column] = Whodunit::Current.user_id
+    end
+
+    # Set the deleter ID when a record is destroyed.
+    #
+    # This method is automatically called before_destroy if the model has a deleter column
+    # and soft-delete is enabled. It sets the deleter_id to the current user from Whodunit::Current.
+    #
+    # @return [void]
+    # @api private
+    def set_whodunit_deleter
+      return unless Whodunit::Current.user_id
+
+      self[Whodunit.deleter_column] = Whodunit::Current.user_id
+    end
+
+    # @!group Column Presence Checks
+
+    # Check if the model has a creator column.
+    #
+    # @return [Boolean] true if the creator column exists
+    # @api private
+    def creator_column?
+      self.class.column_names.include?(Whodunit.creator_column.to_s)
+    end
+
+    # Check if the model has an updater column.
+    #
+    # @return [Boolean] true if the updater column exists
+    # @api private
+    def updater_column?
+      self.class.column_names.include?(Whodunit.updater_column.to_s)
+    end
+
+    # Check if the model has a deleter column.
+    #
+    # @return [Boolean] true if the deleter column exists
+    # @api private
+    def deleter_column?
+      self.class.column_names.include?(Whodunit.deleter_column.to_s)
+    end
+  end
+end

data/lib/whodunit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Whodunit
+  VERSION = "0.1.0"
+end