whodunit 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3f89bd20ea577eb0a740137c86a7927500ccd189e9d9375d18b21c0b36ffdc
-  data.tar.gz: 20586d959bc0d25a47319f615f333021d1ebbec331d865c6a18400987f24ef39
+  metadata.gz: 3c21f2da7abe6b4a2b1440a155e75f28e8e73fea5bcd5cc4169a8c07c49a02c4
+  data.tar.gz: f1e0a0978d93eeff03293f1fe92b1aabcc536bd043e2972b28d360dd4c9e4259
 SHA512:
-  metadata.gz: 5cca573bee0c6d0313d5adf4079e18996d4bc5ecf354b7de39f77e9537b078c67d6122d4a2a7c8c3314ec9da44f40a5ec262a573c06e12b092f86935a951b327
-  data.tar.gz: 810bd48aaf36a9605802c62d8f6616d0d68eb63b78a2f92c955c0f06b0cc609f0f6c729274bfc33d5caf42e8263ce8a49d4aa253480db7103dd0c0ea756ce5e1
+  metadata.gz: 8a42ff533dd671e32a8a409a8bdd90ddb74b3dd34ab015cdfccabaee192761e8b1f629ff145cc22bf9db08d131e63009c1698a730710177434c2b46337f2a893
+  data.tar.gz: 9d5663c7629baa96a6076c6e3b8e4b4f201ced618653e5a27e3a8273db0bfe3ae7a99b6451518361af04e2793a4f0d17564f0959c33dc3028cdd34fe82d0ce9d

data/.rubocop.yml

@@ -43,6 +43,11 @@ Metrics/MethodLength:
 Metrics/ModuleLength:
   Exclude:
     - 'lib/whodunit.rb'
+    - 'lib/whodunit/migration_helpers.rb'
+
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/whodunit/migration_helpers.rb'
 
 # RSpec specific configurations
 RSpec/ExampleLength:
@@ -113,6 +118,7 @@ Metrics/AbcSize:
   Max: 20
   Exclude:
     - 'spec/**/*'
+    - 'lib/whodunit/migration_helpers.rb'
 
 Metrics/CyclomaticComplexity:
   Max: 10

data/CHANGELOG.md

@@ -1,9 +1,23 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## Unreleased
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.5.0] - 2026-08-20
+
+### Added
+
+- Added `auto_create_user_fk_constraints` configuration for automatically creating foreign-key constraints from creator, updater, and deleter stamp columns to the configured user table.
+- Added `user_class_table_name` for explicitly overriding the inferred user table name.
+- Added per-migration overrides for automatic user foreign-key creation.
+- Added automatic injection of the configured soft-delete timestamp alongside the deleter stamp column.
+
+### Fixed
+
+- Made stamp auto-injection idempotent when migrations already declare stamp columns or matching foreign keys.
+- Removed stamp foreign-key constraints before removing stamp columns in migration helpers.
+- Avoided loading the configured user model while migrations infer its table name, preventing failures when the user table is being created in the same migration.
+- Skipped automatic stamp and user-FK injection for Rails internal metadata tables during database setup.
+- Made `require "whodunit"` safe before Active Record loads by deferring migration integration until Active Record is available.
 
 ## [0.4.1] - 2026-06-01
 

data/README.md

@@ -208,6 +208,8 @@ Whodunit.configure do |config|
   config.deleter_column = :deleted_by_id    # Default: :deleter_id
   config.soft_delete_column = :discarded_at # Default: nil
   config.auto_inject_whodunit_stamps = false # Default: true
+  config.auto_create_user_fk_constraints = false # Default: false
+  # config.user_class_table_name = :accounts   # Optional explicit table name
 
   # Reverse association configuration
   config.auto_setup_reverse_associations = false # Default: true
@@ -222,6 +224,40 @@ Whodunit.configure do |config|
 end
 ```
 
+When `auto_create_user_fk_constraints` is enabled, migration helpers add
+foreign-key constraints from the configured creator, updater, and deleter
+columns to the configured user table. The user table is inferred from
+`user_class` unless `user_class_table_name` is set explicitly.
+For the standard `User` model, Whodunit infers `users`; setting
+`user_class_table_name` is not required. Use it only when the model maps to a
+nonstandard table name or when you want to make that mapping explicit.
+
+**Caution:** the referenced user table must be created before migrations that
+create these foreign keys. The user model is not loaded while resolving the
+table name, so a user table can safely use automatic stamps in its own
+migration. Use `auto_create_user_fk_constraints: false` for migrations that
+must run before the user table exists.
+
+Automatic injection intentionally skips Rails internal metadata tables such as
+`ar_internal_metadata` and `schema_migrations`.
+
+When `soft_delete_column` is configured, `include_deleter: :auto` also adds
+the configured soft-delete timestamp and deleter columns to new tables. The
+injection is idempotent when either column was declared explicitly. Pass
+`include_deleter: false` to omit only the deleter audit column for a specific
+table.
+
+The setting can be overridden for an individual migration:
+
+```ruby
+create_table :posts do |t|
+  t.timestamps
+  t.whodunit_stamps auto_create_user_fk_constraints: false
+end
+
+add_whodunit_stamps :legacy_posts, auto_create_user_fk_constraints: true
+```
+
 ### Data Type Configuration
 
 By default, all stamp columns use `:bigint` data type. You can customize this in several ways:

data/lib/whodunit/generator.rb

@@ -26,7 +26,7 @@ module Whodunit
       #   config.updater_column = :updated_by_id    # Default: :updater_id
       #                                             # Column that stores who last updated the record
       #   config.deleter_column = :deleted_by_id    # Default: :deleter_id
-      #                                             # Column that stores who deleted the record (soft-delete only)
+      #                                             # Column that stores who performed the delete operation
       #
       #   # Soft-delete integration
       #   # Enable tracking of who deleted records when using soft-delete gems
@@ -39,8 +39,11 @@ module Whodunit
       #   # Migration auto-injection
       #   # Control whether whodunit stamps are automatically added to new migrations
       #   config.auto_inject_whodunit_stamps = false # Default: true
-      #                                               # When true, automatically adds t.whodunit_stamps to create_table migrations
+      #                                               # When true, automatically adds stamps to create_table definitions using timestamps
       #                                               # When false, you must manually add t.whodunit_stamps to your migrations
+      #   config.auto_create_user_fk_constraints = false # Default: false
+      #                                               # When true, adds foreign keys from stamp columns to the user table
+      #   # config.user_class_table_name = :accounts   # Optional explicit user table name
       #
       #   # Column data type configuration
       #   # Configure what data types to use for the tracking columns
@@ -55,7 +58,7 @@ module Whodunit
       #   config.updater_column_type = :uuid       # Default: nil (uses column_data_type)
       #                                            # Set to match your user model's primary key type
       #   config.deleter_column_type = :integer    # Default: nil (uses column_data_type)
-      #                                            # Only used when soft_delete_column is configured
+      #                                            # Used whenever the deleter column is injected
       # end
     RUBY
 

data/lib/whodunit/migration_helpers.rb

@@ -74,7 +74,12 @@ module Whodunit
     #   add_whodunit_stamps :posts, include_deleter: true
     # @example Exclude deleter column
     #   add_whodunit_stamps :posts, include_deleter: false
-    def add_whodunit_stamps(table_name, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil)
+    def add_whodunit_stamps(table_name, include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil,
+                            auto_create_user_fk_constraints: nil)
+      if Whodunit.soft_delete_enabled? && !column_exists?(table_name, Whodunit.soft_delete_column)
+        add_column table_name, Whodunit.soft_delete_column, :datetime, null: true
+      end
+
       if Whodunit.creator_enabled?
         add_column table_name, Whodunit.creator_column, creator_type || Whodunit.creator_data_type, null: true
       end
@@ -88,6 +93,7 @@ module Whodunit
       end
 
       add_whodunit_indexes(table_name, include_deleter)
+      add_whodunit_foreign_keys(table_name, include_deleter, auto_create_user_fk_constraints)
     end
 
     # Remove stamp columns from an existing table.
@@ -107,7 +113,9 @@ module Whodunit
     #   remove_whodunit_stamps :posts, include_deleter: true
     # @example Exclude deleter removal
     #   remove_whodunit_stamps :posts, include_deleter: false
-    def remove_whodunit_stamps(table_name, include_deleter: :auto, **_options)
+    def remove_whodunit_stamps(table_name, include_deleter: :auto, auto_create_user_fk_constraints: nil, **_options)
+      remove_whodunit_foreign_keys(table_name, include_deleter, auto_create_user_fk_constraints)
+
       if Whodunit.creator_enabled? && column_exists?(table_name, Whodunit.creator_column)
         remove_column table_name, Whodunit.creator_column
       end
@@ -120,6 +128,10 @@ module Whodunit
          column_exists?(table_name, Whodunit.deleter_column)
         remove_column table_name, Whodunit.deleter_column
       end
+
+      return unless Whodunit.soft_delete_enabled? && column_exists?(table_name, Whodunit.soft_delete_column)
+
+      remove_column table_name, Whodunit.soft_delete_column
     end
 
     # Add stamp columns to a table definition or existing table.
@@ -129,8 +141,7 @@ module Whodunit
     # 2. As a standalone method in migrations (attempts to infer table name)
     #
     # Only adds columns that are enabled in configuration. For new tables,
-    # deleter column is only added when explicitly requested (include_deleter: true)
-    # to be conservative.
+    # include_deleter: :auto follows the configured soft-delete column.
     #
     # @param table_def [ActiveRecord::ConnectionAdapters::TableDefinition, nil]
     #   the table definition (when used in create_table block) or nil
@@ -154,40 +165,52 @@ module Whodunit
     #     t.whodunit_stamps include_deleter: true
     #   end
     def whodunit_stamps(table_def = nil, include_deleter: :auto, creator_type: nil, updater_type: nil,
-                        deleter_type: nil)
+                        deleter_type: nil, auto_create_user_fk_constraints: nil)
       if table_def.nil?
-        handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type)
+        handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type,
+                                auto_create_user_fk_constraints)
       else
-        handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type)
+        handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type,
+                                       auto_create_user_fk_constraints)
       end
     end
 
     private
 
     # Handle stamps when called as migration method
-    def handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type)
+    def handle_migration_stamps(include_deleter, creator_type, updater_type, deleter_type,
+                                auto_create_user_fk_constraints)
       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)
+                                      updater_type: updater_type, deleter_type: deleter_type,
+                                      auto_create_user_fk_constraints: auto_create_user_fk_constraints)
     end
 
     # Handle stamps when called within create_table block
-    def handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type)
-      if Whodunit.creator_enabled?
-        table_def.column Whodunit.creator_column, creator_type || Whodunit.creator_data_type, null: true
-      end
+    def handle_table_definition_stamps(table_def, include_deleter, creator_type, updater_type, deleter_type,
+                                       auto_create_user_fk_constraints)
+      add_whodunit_columns_to_table_definition(table_def, include_deleter, creator_type, updater_type, deleter_type)
+      add_whodunit_indexes_for_create_table(table_def, include_deleter)
+      add_whodunit_foreign_keys_for_create_table(table_def, include_deleter, auto_create_user_fk_constraints)
+    end
 
-      if Whodunit.updater_enabled?
-        table_def.column Whodunit.updater_column, updater_type || Whodunit.updater_data_type, null: true
-      end
+    def add_whodunit_columns_to_table_definition(table_def, include_deleter, creator_type, updater_type, deleter_type)
+      add_table_definition_column(table_def, Whodunit.creator_column, creator_type || Whodunit.creator_data_type,
+                                  Whodunit.creator_enabled?)
+      add_table_definition_column(table_def, Whodunit.updater_column, updater_type || Whodunit.updater_data_type,
+                                  Whodunit.updater_enabled?)
+      add_table_definition_column(table_def, Whodunit.soft_delete_column, :datetime,
+                                  Whodunit.soft_delete_enabled?)
+      add_table_definition_column(table_def, Whodunit.deleter_column, deleter_type || Whodunit.deleter_data_type,
+                                  should_include_deleter_for_new_table?(include_deleter))
+    end
 
-      if should_include_deleter_for_new_table?(include_deleter)
-        table_def.column Whodunit.deleter_column, deleter_type || Whodunit.deleter_data_type, null: true
-      end
+    def add_table_definition_column(table_def, column, type, enabled)
+      return unless enabled && !stamp_column_defined?(table_def, column)
 
-      add_whodunit_indexes_for_create_table(table_def, include_deleter)
+      table_def.column column, type, null: true
     end
 
     # Determine if deleter column should be included based on configuration.
@@ -198,12 +221,11 @@ module Whodunit
       include_deleter == :auto ? soft_delete_enabled? : include_deleter.eql?(true)
     end
 
-    # For new tables, be more conservative - only include deleter when explicitly requested.
-    # This prevents adding deleter columns to tables that may not need them.
+    # Determine whether a new table should include the deleter column.
     # @param include_deleter [Symbol, Boolean] the inclusion preference
-    # @return [Boolean] true only when explicitly requested (true)
+    # @return [Boolean] true when explicitly requested or soft-delete is configured
     def should_include_deleter_for_new_table?(include_deleter)
-      include_deleter.eql?(true)
+      should_include_deleter?(include_deleter)
     end
 
     # Check if soft-delete is enabled based on configuration.
@@ -241,6 +263,60 @@ module Whodunit
       table_def.index Whodunit.deleter_column, name: "index_#{table_name}_on_deleter"
     end
 
+    def add_whodunit_foreign_keys(table_name, include_deleter, override)
+      return unless create_user_fk_constraints?(override)
+
+      add_foreign_key table_name, Whodunit.user_table_name, column: Whodunit.creator_column if Whodunit.creator_enabled?
+      add_foreign_key table_name, Whodunit.user_table_name, column: Whodunit.updater_column if Whodunit.updater_enabled?
+      return unless should_include_deleter?(include_deleter)
+
+      add_foreign_key table_name, Whodunit.user_table_name, column: Whodunit.deleter_column
+    end
+
+    def add_whodunit_foreign_keys_for_create_table(table_def, include_deleter, override)
+      return unless create_user_fk_constraints?(override)
+
+      add_table_definition_foreign_key(table_def, Whodunit.creator_column) if Whodunit.creator_enabled?
+      add_table_definition_foreign_key(table_def, Whodunit.updater_column) if Whodunit.updater_enabled?
+      return unless should_include_deleter_for_new_table?(include_deleter)
+
+      add_table_definition_foreign_key(table_def,
+                                       Whodunit.deleter_column)
+    end
+
+    def stamp_column_defined?(table_def, column_name)
+      table_def.columns.any? { |column| column.name.to_s == column_name.to_s }
+    end
+
+    def add_table_definition_foreign_key(table_def, column_name)
+      return if table_def.foreign_keys.any? do |foreign_key|
+        foreign_key.to_table.to_s == Whodunit.user_table_name.to_s &&
+        foreign_key.options[:column].to_s == column_name.to_s
+      end
+
+      table_def.foreign_key Whodunit.user_table_name, column: column_name
+    end
+
+    def create_user_fk_constraints?(override)
+      override.nil? ? Whodunit.auto_create_user_fk_constraints : override
+    end
+
+    def remove_whodunit_foreign_keys(table_name, include_deleter, override)
+      return unless create_user_fk_constraints?(override)
+
+      if Whodunit.creator_enabled?
+        remove_foreign_key table_name, Whodunit.user_table_name,
+                           column: Whodunit.creator_column
+      end
+      if Whodunit.updater_enabled?
+        remove_foreign_key table_name, Whodunit.user_table_name,
+                           column: Whodunit.updater_column
+      end
+      return unless should_include_deleter?(include_deleter)
+
+      remove_foreign_key table_name, Whodunit.user_table_name, column: Whodunit.deleter_column
+    end
+
     # Attempt to infer table name from migration class name
     def infer_table_name_from_migration
       return nil unless respond_to?(:migration_name)
@@ -249,10 +325,10 @@ module Whodunit
       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"
+        table_name.underscore.pluralize
       when /^Add\w*To(\w+)$/
         table_name = ::Regexp.last_match(1)
-        table_name.respond_to?(:underscore) ? table_name.underscore : table_name.downcase
+        table_name.underscore
       end
     end
 
@@ -263,5 +339,13 @@ module Whodunit
   end
 end
 
-# Extend ActiveRecord::Migration when available
-ActiveRecord::Migration.include(Whodunit::MigrationHelpers) if defined?(ActiveRecord::Migration)
+# Integrate immediately when Active Record is already loaded, or defer until it is.
+# :nocov:
+if defined?(ActiveRecord::Migration)
+  ActiveRecord::Migration.include(Whodunit::MigrationHelpers)
+elsif defined?(ActiveSupport)
+  ActiveSupport.on_load(:active_record) do
+    ActiveRecord::Migration.include(Whodunit::MigrationHelpers)
+  end
+end
+# :nocov:

data/lib/whodunit/stampable.rb

@@ -186,7 +186,7 @@ module Whodunit
       # @return [void]
       # @api private
       def setup_whodunit_associations
-        return if abstract_class?
+        return if abstract_class? || !table_exists?
 
         setup_creator_association if creator_column_exists? && model_creator_enabled?
         setup_updater_association if updater_column_exists? && model_updater_enabled?

data/lib/whodunit/table_definition_extension.rb

@@ -42,7 +42,7 @@ module Whodunit
       skip = options.delete(:skip_whodunit_stamps)
       result = super
 
-      if Whodunit.auto_inject_whodunit_stamps && !_whodunit_stamps_added && !skip
+      if Whodunit.auto_inject_whodunit_stamps && !_whodunit_stamps_added && !skip && !whodunit_internal_table?
         whodunit_stamps(include_deleter: :auto)
       end
 
@@ -52,9 +52,17 @@ module Whodunit
     # assign true tp the tracker `@_whodunit_stamps_added` before the
     # reuse/call of the `whodunit_stamps` flow from the Whodunit::MigrationHelpers module (see railtie.rb)
     #
-    def whodunit_stamps(include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil)
+    def whodunit_stamps(include_deleter: :auto, creator_type: nil, updater_type: nil, deleter_type: nil,
+                        auto_create_user_fk_constraints: nil)
       self._whodunit_stamps_added = true
-      self.class.whodunit_stamps(self, include_deleter:, creator_type:, updater_type:, deleter_type:)
+      self.class.whodunit_stamps(self, include_deleter:, creator_type:, updater_type:, deleter_type:,
+                                       auto_create_user_fk_constraints:)
+    end
+
+    private
+
+    def whodunit_internal_table?
+      %w[ar_internal_metadata schema_migrations].include?(name.to_s)
     end
   end
 end

data/lib/whodunit/version.rb

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

data/lib/whodunit.rb

@@ -43,6 +43,11 @@ module Whodunit
   # @return [String] the user class name
   mattr_accessor :user_class, default: "User"
 
+  # Explicit user table name override. When nil, the table name is inferred
+  # from the configured user class.
+  # @return [String, Symbol, nil] the user table name override
+  mattr_accessor :user_class_table_name, default: nil
+
   # The column name for tracking who created the record (default: :creator_id)
   # @return [Symbol] the creator column name
   mattr_accessor :creator_column, default: :creator_id
@@ -65,6 +70,10 @@ module Whodunit
   # @return [Boolean] auto-injection setting
   mattr_accessor :auto_inject_whodunit_stamps, default: true
 
+  # Whether migration helpers should create foreign keys to the user table.
+  # @return [Boolean] automatic user foreign-key constraint setting
+  mattr_accessor :auto_create_user_fk_constraints, default: false
+
   # @!group Data Type Configuration
 
   # The default data type for stamp columns (default: :bigint)
@@ -132,6 +141,21 @@ module Whodunit
     user_class.to_s
   end
 
+  # Resolve the configured user table name without loading the model. Migration
+  # execution can happen before the user table exists, so constantizing the
+  # user class here may cause Active Record to query a missing relation.
+  # Explicit configuration takes precedence; class objects may still provide
+  # their custom Active Record table name directly.
+  #
+  # @return [String] the user table name
+  def self.user_table_name
+    return user_class_table_name.to_s if user_class_table_name
+
+    return user_class.table_name.to_s if user_class.respond_to?(:table_name)
+
+    user_class_name.underscore.pluralize
+  end
+
   # @!group Data Type Helpers
 
   # Get the data type for the creator column

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whodunit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Ken C. Demanawa
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-31 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord