whodunit 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ce926c88b69914bd703491e1bf11f890f64a4c4f5679929d1b898306ea18fcd
-  data.tar.gz: 3b277cf8bbf1f36e494f90f959941c38b3829f541b5b36b1168b98a276d830f7
+  metadata.gz: 323bc72651528d7bf5e205c0388462078acc718ea39b14b5775517644a2115fc
+  data.tar.gz: d20344c823d5716ae218497ca92f61f41c6660c8e8f27a5479b0e52bc64b6b25
 SHA512:
-  metadata.gz: 68b739ee97b145af1451991f589dfd9353da7ff579592e9f45071c532ed095e2b83e166b30b987bdbd6a22f1f47b421d1dc76fce7818491889376a0249ecdd21
-  data.tar.gz: 3796e3c88a21640063c504d27f3fa34a16f077eac5653826cd7a0a4ad513288dec0aa88383afa633daac57d25719711e2325cc33e01079f00725f76d2d22270d
+  metadata.gz: f893afd5307dfa5cdabd58c8de25baa2e979809f9d2c810cdb5dd029a90ebb07f79a61ab24c149e9545159aafef09b3494e2fe15cdee93a6c66e1ae35c44bd2e
+  data.tar.gz: 9df8c395516af0720e71fd2a5e8b03a3471f4a85684f8b8a7b274222f74a19feeb1bb9a2b5b3e4795fbcf8938aef769a87e1dd380668838198efad31215d4e3b

data/.rubocop.yml

@@ -38,9 +38,17 @@ Metrics/MethodLength:
   Exclude:
     - 'spec/**/*'
 
+# Allow longer modules for main configuration
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/whodunit.rb'
+
 # RSpec specific configurations
 RSpec/ExampleLength:
   Max: 15
+  Exclude:
+    - 'spec/whodunit/reverse_associations_integration_spec.rb'
+    - 'spec/whodunit/reverse_associations_spec.rb'
 
 RSpec/MultipleExpectations:
   Max: 5
@@ -54,10 +62,21 @@ RSpec/ContextWording:
 RSpec/DescribeClass:
   Exclude:
     - 'spec/integration/**/*'
+    - 'spec/whodunit/reverse_associations_integration_spec.rb'
 
 RSpec/VerifiedDoubles:
   Enabled: false
 
+RSpec/MessageSpies:
+  Exclude:
+    - 'spec/whodunit/reverse_associations_integration_spec.rb'
+    - 'spec/whodunit/reverse_associations_spec.rb'
+    - 'spec/whodunit/stampable_spec.rb'
+
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/whodunit/reverse_associations_spec.rb'
+
 # Allow positional boolean arguments for standard Ruby method signatures
 Style/OptionalBooleanParameter:
   Exclude:

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-01-24
+
+### Added
+
+- **Automatic Reverse Associations**: When models include `Whodunit::Stampable`, reverse associations are automatically created on the user class (e.g., `user.created_posts`, `user.updated_comments`, `user.deleted_documents`)
+- **Model Registry System**: Tracks models that include Stampable for automatic reverse association setup
+- **Per-Model Reverse Association Control**: Models can disable reverse associations with `disable_whodunit_reverse_associations!`
+- **Reverse Association Configuration**: Global configuration options including `auto_setup_reverse_associations`, `reverse_association_prefix`, and `reverse_association_suffix`
+- **Smart Model Capability Detection**: Automatically detects which associations to create based on model capabilities (creator, updater, deleter, soft-delete)
+- **Custom Column Support**: Reverse associations respect per-model custom column configurations
+- **Manual Setup Methods**: `setup_whodunit_reverse_associations!` and `setup_all_reverse_associations` for manual control
+
+### Changed
+
+- **Enhanced Stampable Module**: Now automatically registers models for reverse association setup when included
+- **Improved Configuration**: Extended main configuration module with reverse association settings
+- **Better Association Management**: Prevents duplicate associations and handles edge cases gracefully
+
+### Features
+
+- **Zero Configuration**: Reverse associations work automatically with sensible defaults
+- **Thread Safe**: Built on existing thread-safe architecture
+- **Flexible Naming**: Configurable prefixes and suffixes for association names
+- **Comprehensive Testing**: Full test coverage for all reverse association functionality
+- **RuboCop Compliant**: All code follows project style guidelines
+
 ## [0.2.1] - 2025-01-21
 
 ### Added

data/README.md

@@ -1,5 +1,11 @@
 # Whodunit
 
+[![Gem Version](https://badge.fury.io/rb/whodunit.svg)](https://badge.fury.io/rb/whodunit)
+[![CI](https://github.com/kanutocd/whodunit/workflows/CI/badge.svg)](https://github.com/kanutocd/whodunit/actions)
+[![Coverage Status](https://codecov.io/gh/kanutocd/whodunit/branch/main/graph/badge.svg)](https://codecov.io/gh/kanutocd/whodunit)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-ruby.svg)](https://www.ruby-lang.org/en/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Lightweight creator/updater/deleter tracking for Rails ActiveRecord models.
 
 > **Fun Fact**: The term "whodunit" was coined by literary critic Donald Gordon in 1930 when reviewing a murder mystery novel for _American News of Books_. He described Milward Kennedy's _Half Mast Murder_ as "a satisfactory whodunit" - the first recorded use of this now-famous term for mystery stories! _([Source: Wikipedia](https://en.wikipedia.org/wiki/Whodunit))_
@@ -39,10 +45,13 @@ And then execute:
 After installation, you have a few options:
 
 1. **Generate Configuration & Setup** (Recommended):
+
    ```bash
    whodunit install
    ```
+
    This will:
+
    - Create `config/initializers/whodunit.rb` with all available configuration options
    - Optionally add `Whodunit::Stampable` to your `ApplicationRecord` for automatic stamping on all models
    - Provide clear next steps for adding stamp columns to your database
@@ -123,6 +132,51 @@ user.updater   # => User who last updated this record
 user.deleter   # => User who deleted this record (if soft-delete enabled)
 ```
 
+## Reverse Associations (Automatic)
+
+Whodunit automatically sets up reverse associations on your User model when you include `Whodunit::Stampable` in other models:
+
+```ruby
+# When you include Whodunit::Stampable in Post model:
+class Post < ApplicationRecord
+  include Whodunit::Stampable
+end
+
+# Your User model automatically gets these associations:
+user.created_posts   # => Posts created by this user
+user.updated_posts   # => Posts last updated by this user  
+user.deleted_posts   # => Posts deleted by this user (if soft-delete enabled)
+```
+
+### Configuring Reverse Associations
+
+```ruby
+# config/initializers/whodunit.rb
+Whodunit.configure do |config|
+  # Disable automatic reverse associations globally
+  config.auto_setup_reverse_associations = false
+  
+  # Customize association names with prefix/suffix
+  config.reverse_association_prefix = "whodunit_"
+  config.reverse_association_suffix = "_tracked"
+  # Results in: user.whodunit_created_posts_tracked
+end
+```
+
+### Per-Model Control
+
+```ruby
+class Post < ApplicationRecord
+  include Whodunit::Stampable
+  
+  # Disable reverse associations for this model only
+  disable_whodunit_reverse_associations!
+end
+
+# Or manually set up later
+Post.setup_whodunit_reverse_associations!
+```
+
 ## Soft-Delete Support
 
 Whodunit automatically tracks who deleted records when using soft-delete. Simply configure your soft-delete column:
@@ -155,6 +209,11 @@ Whodunit.configure do |config|
   config.soft_delete_column = :discarded_at # Default: nil
   config.auto_inject_whodunit_stamps = false # Default: true
 
+  # Reverse association configuration
+  config.auto_setup_reverse_associations = false # Default: true
+  config.reverse_association_prefix = "track_"   # Default: ""
+  config.reverse_association_suffix = "_logs"    # Default: ""
+
   # Column data type configuration
   config.column_data_type = :integer       # Default: :bigint (applies to all columns)
   config.creator_column_type = :string     # Default: nil (uses column_data_type)
@@ -344,7 +403,7 @@ end
 | Feature               | Whodunit | PaperTrail | Audited |
 | --------------------- | -------- | ---------- | ------- |
 | User tracking         | ✅       | ✅         | ✅      |
-| Change history        | ❌       | ✅         | ✅      |
+| Change history        | Via [whodunit-chronicles](https://github.com/kanutocd/whodunit-chronicles) | ✅         | ✅      |
 | Performance overhead  | None     | High       | Medium  |
 | Soft-delete detection | ✅       | ❌         | ❌      |
 | Setup complexity      | Low      | Medium     | Medium  |

data/lib/whodunit/stampable.rb

@@ -52,6 +52,10 @@ module Whodunit
 
       # Set up associations - call on the class
       setup_whodunit_associations
+
+      # Register this model for reverse association setup
+      # This happens immediately, but the check for enabled status is done in register_model
+      Whodunit.register_model(self)
     end
 
     class_methods do # rubocop:disable Metrics/BlockLength
@@ -82,6 +86,31 @@ module Whodunit
         @soft_delete_enabled = false
       end
 
+      # Disable reverse association setup for this model
+      # Call this method in the model class to prevent automatic reverse associations
+      # @example
+      #   class Post < ApplicationRecord
+      #     include Whodunit::Stampable
+      #     disable_whodunit_reverse_associations!
+      #   end
+      def disable_whodunit_reverse_associations!
+        @whodunit_reverse_associations_disabled = true
+        # Remove from registered models if already registered
+        Whodunit.registered_models.delete(self)
+      end
+
+      # Check if reverse associations are enabled for this model
+      # @return [Boolean] true if reverse associations should be set up
+      def whodunit_reverse_associations_enabled?
+        !@whodunit_reverse_associations_disabled
+      end
+
+      # Manually set up reverse associations for this model
+      # Can be called if reverse associations were disabled but you want to set them up later
+      def setup_whodunit_reverse_associations!
+        Whodunit.setup_reverse_associations_for_model(self) if whodunit_reverse_associations_enabled?
+      end
+
       # Get effective configuration value (model override or global default)
       def whodunit_setting(key)
         return @whodunit_config_overrides[key] if @whodunit_config_overrides&.key?(key)

data/lib/whodunit/version.rb

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

data/lib/whodunit.rb

@@ -83,6 +83,31 @@ module Whodunit
   # @return [Symbol, nil] the deleter column data type
   mattr_accessor :deleter_column_type, default: nil
 
+  # @!group Reverse Association Configuration
+
+  # Whether to automatically set up reverse associations on the user class (default: true)
+  # When enabled, including Whodunit::Stampable in a model will automatically add
+  # has_many associations to the user class (e.g., has_many :created_posts)
+  # @return [Boolean] auto reverse association setting
+  mattr_accessor :auto_setup_reverse_associations, default: true
+
+  # Prefix for reverse association names (default: "")
+  # Used to generate association names like "created_posts", "updated_comments"
+  # @return [String] the prefix for reverse association names
+  mattr_accessor :reverse_association_prefix, default: ""
+
+  # Suffix for reverse association names (default: "")
+  # Used to generate association names like "posts_created", "comments_updated"
+  # @return [String] the suffix for reverse association names
+  mattr_accessor :reverse_association_suffix, default: ""
+
+  # @!group Model Registry
+
+  # Registry to track models that include Whodunit::Stampable
+  # This is used to set up reverse associations on the user class
+  # @return [Array<Class>] array of model classes that include Stampable
+  mattr_accessor :registered_models, default: []
+
   # Configure Whodunit settings
   #
   # @example
@@ -151,6 +176,135 @@ module Whodunit
     !deleter_column.nil?
   end
 
+  # @!group Model Registration & Reverse Associations
+
+  # Register a model class that includes Whodunit::Stampable
+  # This is called automatically when Stampable is included
+  # @param [Class] model_class the model class to register
+  # @return [void]
+  def self.register_model(model_class)
+    return unless auto_setup_reverse_associations
+    return if registered_models.include?(model_class)
+    return if model_class.respond_to?(:whodunit_reverse_associations_enabled?) &&
+              !model_class.whodunit_reverse_associations_enabled?
+
+    registered_models << model_class
+    setup_reverse_associations_for_model(model_class)
+  end
+
+  # Set up reverse associations on the user class for a specific model
+  # @param [Class] model_class the model class to set up reverse associations for
+  # @return [void]
+  def self.setup_reverse_associations_for_model(model_class)
+    return unless auto_setup_reverse_associations
+
+    user_class_instance = resolve_user_class
+    return unless user_class_instance.respond_to?(:has_many)
+
+    model_plural = model_class.name.underscore.pluralize
+
+    setup_creator_reverse_association(user_class_instance, model_class, model_plural)
+    setup_updater_reverse_association(user_class_instance, model_class, model_plural)
+    setup_deleter_reverse_association(user_class_instance, model_class, model_plural)
+  end
+
+  # Set up all reverse associations for all registered models
+  # This can be called manually if needed (e.g., after configuration changes)
+  # @return [void]
+  def self.setup_all_reverse_associations
+    registered_models.each do |model_class|
+      setup_reverse_associations_for_model(model_class)
+    end
+  end
+
+  # Generate a reverse association name based on action and model name
+  # @param [String] action the action (created, updated, deleted)
+  # @param [String] model_plural the pluralized model name
+  # @return [String] the generated association name
+  def self.generate_reverse_association_name(action, model_plural)
+    "#{reverse_association_prefix}#{action}_#{model_plural}#{reverse_association_suffix}"
+  end
+
+  # Resolve the user class constant
+  # @return [Class, nil] the user class or nil if not found
+  def self.resolve_user_class
+    user_class.constantize
+  rescue StandardError
+    nil
+  end
+
+  # Set up creator reverse association
+  # @param [Class] user_class_instance the user class
+  # @param [Class] model_class the model class
+  # @param [String] model_plural the pluralized model name
+  # @return [void]
+  def self.setup_creator_reverse_association(user_class_instance, model_class, model_plural)
+    return unless model_class.respond_to?(:model_creator_enabled?) && model_class.model_creator_enabled?
+
+    association_name = generate_reverse_association_name("created", model_plural)
+    setup_user_reverse_association(user_class_instance, association_name, model_class, :creator_id)
+  end
+
+  # Set up updater reverse association
+  # @param [Class] user_class_instance the user class
+  # @param [Class] model_class the model class
+  # @param [String] model_plural the pluralized model name
+  # @return [void]
+  def self.setup_updater_reverse_association(user_class_instance, model_class, model_plural)
+    return unless model_class.respond_to?(:model_updater_enabled?) && model_class.model_updater_enabled?
+
+    association_name = generate_reverse_association_name("updated", model_plural)
+    setup_user_reverse_association(user_class_instance, association_name, model_class, :updater_id)
+  end
+
+  # Set up deleter reverse association
+  # @param [Class] user_class_instance the user class
+  # @param [Class] model_class the model class
+  # @param [String] model_plural the pluralized model name
+  # @return [void]
+  def self.setup_deleter_reverse_association(user_class_instance, model_class, model_plural)
+    return unless model_class.respond_to?(:model_deleter_enabled?) && model_class.model_deleter_enabled?
+    return unless model_class.respond_to?(:soft_delete_enabled?) && model_class.soft_delete_enabled?
+
+    association_name = generate_reverse_association_name("deleted", model_plural)
+    setup_user_reverse_association(user_class_instance, association_name, model_class, :deleter_id)
+  end
+
+  # Set up a specific reverse association on the user class
+  # @param [Class] user_class_instance the user class
+  # @param [String] association_name the name of the association
+  # @param [Class] model_class the model class
+  # @param [Symbol] foreign_key_column the foreign key column name
+  # @return [void]
+  def self.setup_user_reverse_association(user_class_instance, association_name, model_class, foreign_key_column)
+    actual_foreign_key = resolve_foreign_key(model_class, foreign_key_column)
+
+    # Check if association already exists to avoid duplicates
+    return if user_class_instance.reflect_on_association(association_name.to_sym)
+
+    user_class_instance.has_many association_name.to_sym,
+                                 class_name: model_class.name,
+                                 foreign_key: actual_foreign_key,
+                                 dependent: :nullify
+  end
+
+  # Resolve the actual foreign key column name from model configuration
+  # @param [Class] model_class the model class
+  # @param [Symbol] foreign_key_column the default foreign key column
+  # @return [Symbol] the actual foreign key column name
+  def self.resolve_foreign_key(model_class, foreign_key_column)
+    return foreign_key_column unless model_class.respond_to?(:whodunit_setting)
+
+    column_mapping = {
+      creator_id: :creator_column,
+      updater_id: :updater_column,
+      deleter_id: :deleter_column
+    }
+
+    setting_key = column_mapping[foreign_key_column]
+    setting_key ? (model_class.whodunit_setting(setting_key) || foreign_key_column) : foreign_key_column
+  end
+
   # Validate that column configuration is valid
   # @raise [Whodunit::Error] if both creator_column and updater_column are nil
   def self.validate_column_configuration!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whodunit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-21 00:00:00.000000000 Z
+date: 2025-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord