model_timeline 0.1.0

data/lib/model_timeline/rspec/matchers.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  module RSpec
+    # rubocop:disable Naming/PredicateName
+    # Custom RSpec matchers for testing model timeline entries
+    #
+    # These matchers help you test the timeline entries created by the ModelTimeline gem.
+    # Use them in your specs to verify that your models are correctly recording timeline events.
+    #
+    # @example Basic usage with different matchers
+    #   # Check for any timeline entries
+    #   expect(user).to have_timeline_entries
+    #
+    #   # Check for specific number of entries
+    #   expect(user).to have_timeline_entries(3)
+    #
+    #   # Check for specific action
+    #   expect(user).to have_timelined_action(:update)
+    #
+    #   # Check for changes to a specific attribute
+    #   expect(user).to have_timelined_change(:email)
+    #
+    #   # Check for specific value change
+    #   expect(user).to have_timelined_entry(:status, "active")
+    module Matchers
+      # Check if a model has timeline entries
+      #
+      # @param count [Integer, nil] The expected number of timeline entries (optional)
+      # @return [HaveTimelineEntriesMatcher] A matcher that checks for timeline entries
+      # @example Without count parameter
+      #   expect(user).to have_timeline_entries
+      # @example With count parameter
+      #   expect(user).to have_timeline_entries(3)
+      def have_timeline_entries(count = nil)
+        HaveTimelineEntriesMatcher.new(count)
+      end
+
+      # Check if a specific action was recorded in the timeline
+      #
+      # @param action [String, Symbol] The action name to look for
+      # @return [HaveTimelinedAction] A matcher that checks for a specific action
+      # @example
+      #   expect(user).to have_timelined_action(:create)
+      #   expect(user).to have_timelined_action("update")
+      def have_timelined_action(action)
+        HaveTimelinedAction.new(action)
+      end
+
+      # Check if a specific attribute change was recorded in the timeline
+      #
+      # @param attribute [String, Symbol] The attribute name to check for changes
+      # @return [HaveTimelinedChange] A matcher that checks if an attribute was changed
+      # @example
+      #   expect(user).to have_timelined_change(:email)
+      #   expect(user).to have_timelined_change("status")
+      def have_timelined_change(attribute)
+        HaveTimelinedChange.new(attribute)
+      end
+
+      # Check if an attribute was changed to a specific value in the timeline
+      #
+      # @param attribute [String, Symbol] The attribute name to check
+      # @param value [Object] The value to check for
+      # @return [HaveTimelinedEntry] A matcher that checks for specific attribute values
+      # @example
+      #   expect(user).to have_timelined_entry(:status, "active")
+      #   expect(user).to have_timelined_entry(:role, :admin)
+      def have_timelined_entry(attribute, value)
+        HaveTimelinedEntry.new(attribute, value)
+      end
+
+      # RSpec matcher to check if a model has timeline entries
+      #
+      # @api private
+      class HaveTimelineEntriesMatcher
+        # Initialize the matcher
+        #
+        # @param expected_count [Integer, nil] The expected number of timeline entries
+        def initialize(expected_count)
+          @expected_count = expected_count
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has the expected number of timeline entries
+        def matches?(subject)
+          @subject = subject
+          if @expected_count.nil?
+            subject.timeline_entries.any?
+          else
+            subject.timeline_entries.count == @expected_count
+          end
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          if @expected_count.nil?
+            "expected #{@subject} to have timeline entries, but found none"
+          else
+            "expected #{@subject} to have #{@expected_count} timeline entries, " \
+              "but found #{@subject.timeline_entries.count}"
+          end
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          if @expected_count.nil?
+            "expected #{@subject} not to have any timeline entries, but found #{@subject.timeline_entries.count}"
+          else
+            "expected #{@subject} not to have #{@expected_count} timeline entries, but found exactly that many"
+          end
+        end
+      end
+
+      # RSpec matcher to check if a model has timeline entries with a specific action
+      #
+      # @api private
+      class HaveTimelinedAction
+        # Initialize the matcher
+        #
+        # @param action [String, Symbol] The action to look for
+        def initialize(action)
+          @action = action.to_s
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has timeline entries with the specified action
+        def matches?(subject)
+          @subject = subject
+          subject.timeline_entries.where(action: @action).exists?
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          "expected #{@subject} to have recorded action '#{@action}', but none was found"
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          "expected #{@subject} not to have recorded action '#{@action}', but it was found"
+        end
+      end
+
+      # RSpec matcher to check if a model has timeline entries with changes to a specific attribute
+      #
+      # @api private
+      class HaveTimelinedChange
+        # Initialize the matcher
+        #
+        # @param attribute [String, Symbol] The attribute to check for changes
+        def initialize(attribute)
+          @attribute = attribute.to_s
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has timeline entries with changes to the specified attribute
+        def matches?(subject)
+          @subject = subject
+          subject.timeline_entries.with_changed_attribute(@attribute).exists?
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          "expected #{@subject} to have tracked changes to '#{@attribute}', but none was found"
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          "expected #{@subject} not to have tracked changes to '#{@attribute}', but changes were found"
+        end
+      end
+
+      # RSpec matcher to check if a model has timeline entries where an attribute changed to a specific value
+      #
+      # @api private
+      class HaveTimelinedEntry
+        # Initialize the matcher
+        #
+        # @param attribute [String, Symbol] The attribute to check
+        # @param value [Object] The value the attribute should have changed to
+        def initialize(attribute, value)
+          @attribute = attribute.to_s
+          @value = value
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has timeline entries where the attribute changed to the specified value
+        def matches?(subject)
+          @subject = subject
+          subject.timeline_entries.with_changed_value(@attribute, @value).exists?
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          "expected #{@subject} to have tracked '#{@attribute}' changing to '#{@value}', but no such change was found"
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          "expected #{@subject} not to have tracked '#{@attribute}' changing to '#{@value}', but such a change was found"
+        end
+      end
+    end
+    # rubocop:enable Naming/PredicateName
+  end
+end

data/lib/model_timeline/rspec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'model_timeline/rspec/matchers'
+module ModelTimeline
+  # Helper module that configures RSpec to work with ModelTimeline
+  #
+  # This module provides RSpec configuration for ModelTimeline, including:
+  # - Disabling timeline recording by default for faster tests
+  # - Enabling timeline recording only when specifically requested
+  # - Including custom RSpec matchers for testing timeline entries
+  #
+  # @example Including in RSpec configuration
+  #   # In spec_helper.rb or rails_helper.rb
+  #   RSpec.configure do |config|
+  #     config.include ModelTimelineHelper
+  #   end
+  #
+  # @example Running a test with timeline recording enabled
+  #   # Use the :with_timeline metadata to enable recording
+  #   describe User, :with_timeline do
+  #     it "records timeline entries when updated" do
+  #       user.update(name: "New Name")
+  #       expect(user).to have_timelined_change(:name)
+  #     end
+  #   end
+  module RSpec
+    # Configures RSpec with ModelTimeline hooks when included
+    #
+    # @param config [RSpec::Core::Configuration] The RSpec configuration object
+    # @return [void]
+    def self.included(config)
+      # Reset timeline state before each example
+      config.before(:each) do |example|
+        ModelTimeline.disable! unless example.metadata[:with_timeline]
+      end
+
+      # Enable timeline when the :with_timeline metadata is present
+      config.around(:each, :with_timeline) do |example|
+        ModelTimeline.enable!
+        example.run
+      ensure
+        ModelTimeline.disable!
+      end
+
+      # Include custom RSpec matchers for testing timeline entries
+      config.include ModelTimeline::RSpec::Matchers
+    end
+  end
+end

data/lib/model_timeline/timeline_entry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Represents a timeline entry that records changes to a model.
+  # TimelineEntry stores the tracked object, user who made the change,
+  # IP address, and the changes that were made.
+  #
+  class TimelineEntry < ActiveRecord::Base
+    self.table_name = 'model_timeline_timeline_entries'
+
+    # @!attribute timelineable
+    #   @return [Object] The model instance that this timeline entry belongs to
+    belongs_to :timelineable, polymorphic: true, optional: true
+
+    # @!attribute user
+    #   @return [Object] The user who made the change
+    belongs_to :user, polymorphic: true, optional: true
+
+    # Retrieves timeline entries for a specific timelineable object
+    #
+    # @param [Object] timelineable The object to find timeline entries for
+    # @return [ActiveRecord::Relation] Timeline entries for the specified object
+    def self.for_timelineable(timelineable)
+      where(timelineable_type: timelineable.class.name, timelineable_id: timelineable.id)
+    end
+
+    # Retrieves timeline entries created by a specific user
+    #
+    # @param [Object] user The user who created the timeline entries
+    # @return [ActiveRecord::Relation] Timeline entries created by the specified user
+    def self.for_user(user)
+      where(user_type: user.class.name, user_id: user.id)
+    end
+
+    # Retrieves timeline entries from a specific IP address
+    #
+    # @param [String] ip The IP address to search for
+    # @return [ActiveRecord::Relation] Timeline entries from the specified IP address
+    def self.for_ip_address(ip)
+      where(ip_address: ip)
+    end
+
+    # Retrieves timeline entries where a specific attribute was changed
+    #
+    # @param [Symbol, String] attribute The attribute name to check for changes
+    # @return [ActiveRecord::Relation] Timeline entries where the specified attribute changed
+    def self.with_changed_attribute(attribute)
+      where('object_changes ? :key', key: attribute.to_s)
+    end
+
+    # Retrieves timeline entries where an attribute was changed to a specific value
+    #
+    # @param [Symbol, String] attribute The attribute name to check
+    # @param [Object] value The value the attribute was changed to
+    # @return [ActiveRecord::Relation] Timeline entries matching the attribute and value change
+    def self.with_changed_value(attribute, value)
+      where('object_changes -> :key ->> 1 = :value', key: attribute.to_s, value: value.to_s)
+    end
+  end
+end

data/lib/model_timeline/timelineable.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Provides timeline tracking functionality for ActiveRecord models.
+  # When included in a model, this module allows tracking changes to model attributes
+  # over time by creating timeline entries.
+  #
+  # @example Basic usage
+  #   class User < ApplicationRecord
+  #     has_timeline
+  #   end
+  #
+  # @example With custom options
+  #   class Product < ApplicationRecord
+  #     has_timeline :product_history,
+  #                 only: [:name, :price],
+  #                 on: [:update, :destroy]
+  #   end
+  #
+  module Timelineable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :loggers, default: {}
+    end
+
+    # Methods that will be added as class methods to the including class
+    class_methods do
+      # Enables timeline tracking for the model.
+      # This method configures the model to record timeline entries on various
+      # lifecycle events (create, update, destroy).
+      #
+      # @param association_name [Symbol] The name for the timeline entries association
+      # @param options [Hash] Configuration options
+      # @option options [Array<Symbol>] :on ([:create, :update, :destroy]) Which events to track
+      # @option options [Array<Symbol>] :only Limit tracking to these attributes only
+      # @option options [Array<Symbol>] :ignore ([]) Attributes to exclude from tracking
+      # @option options [String] :class_name ('ModelTimeline::TimelineEntry') The timeline entry class
+      # @option options [Hash] :meta ({}) Additional metadata to include with each entry
+      # @return [void]
+      # @raise [ModelTimeline::ConfigurationError] If timeline has already been configured
+      #
+      # @example Track all changes
+      #   has_timeline
+      #
+      # @example Track only specific attributes
+      #   has_timeline(only: [:name, :status])
+      #
+      # @example Use a custom association name
+      #   has_timeline(:audit_log)
+      #
+      # @example Add metadata to entries
+      #   has_timeline(meta: { app_version: APP_VERSION })
+      #
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable Naming/PredicateName
+      def has_timeline(*args, **kwargs)
+        association_name = args.first.is_a?(Symbol) ? args.shift : :timeline_entries
+
+        klass = (kwargs[:class_name] || 'ModelTimeline::TimelineEntry').constantize
+
+        config = {
+          on: kwargs[:on] || %i[create update destroy],
+          only: kwargs[:only],
+          ignore: kwargs[:ignore] || [],
+          klass: klass,
+          meta: kwargs[:meta] || {}
+        }
+
+        config_key = "#{to_s.underscore}-#{klass}"
+        raise ::ModelTimeline::ConfigurationError if loggers[config_key].present?
+
+        loggers[config_key] = config
+
+        after_save -> { log_after_save(config_key) } if config[:on].include?(:create) || config[:on].include?(:update)
+
+        after_destroy -> { log_audit_deletion(config_key) } if config[:on].include?(:destroy)
+
+        has_many association_name.to_sym, class_name: klass.name, as: :timelineable
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+      # rubocop:enable Naming/PredicateName
+    end
+
+    private
+
+      # Records timeline entries after a model is saved (create or update)
+      #
+      # @param config_key [String] The configuration key for this model
+      # @return [void]
+      def log_after_save(config_key)
+        return unless ModelTimeline.enabled?
+
+        config = self.class.loggers[config_key]
+        return unless config
+
+        object_changes = filter_attributes(previous_changes, config)
+        return if object_changes.empty?
+
+        action = previously_new_record? ? :create : :update
+        return unless config[:on].include?(action)
+
+        config[:klass].create!(
+          timelineable_type: self.class.name,
+          timelineable_id: id,
+          action: action,
+          object_changes: object_changes,
+          ip_address: current_ip_address,
+          **current_user_attributes,
+          **collect_metadata(config[:meta], config_key)
+        )
+      end
+
+      # Records timeline entries after a model is destroyed
+      #
+      # @param config_key [String] The configuration key for this model
+      # @return [void]
+      def log_audit_deletion(config_key)
+        return unless ModelTimeline.enabled?
+
+        config = self.class.loggers[config_key]
+        return unless config
+
+        config[:klass].create!(
+          timelineable_type: self.class.name,
+          timelineable_id: id,
+          action: 'destroy',
+          object_changes: {},
+          ip_address: current_ip_address,
+          **current_user_attributes,
+          **collect_metadata(config[:meta], config_key)
+        )
+      end
+
+      # Gets the current user ID if available
+      #
+      # @return [Integer, nil] The current user ID or nil if not available
+      def current_user_id
+        return unless respond_to?(ModelTimeline.current_user_method)
+
+        user = send(ModelTimeline.current_user_method)
+        user.respond_to?(:id) ? user.id : nil
+      end
+
+      # Gets the current IP address from the request store
+      #
+      # @return [String, nil] The current IP address or nil if not available
+      def current_ip_address
+        ModelTimeline.current_ip
+      end
+
+      # Prepares user attributes for the timeline entry
+      #
+      # @return [Hash] User attributes for the timeline entry
+      def current_user_attributes
+        user = ModelTimeline.current_user
+        return {} if user.nil?
+
+        return { username: user.to_s } if user.is_a?(String) || user.is_a?(Symbol)
+
+        return { user_id: user.id, user_type: user.class.name } if user.respond_to?(:id) &&
+                                                                   user.class.ancestors.include?(ActiveRecord::Base)
+
+        return { username: user.to_s } if user.respond_to?(:to_s)
+
+        {}
+      end
+
+      # Filters attributes based on configuration
+      #
+      # @param attrs [Hash] The attributes to filter
+      # @param config [Hash] The timeline configuration
+      # @return [Hash] Filtered attributes
+      def filter_attributes(attrs, config)
+        result = attrs.dup.with_indifferent_access
+        result = result.slice(*config[:only]) if config[:only].present?
+        result = result.except(*config[:ignore]) if config[:ignore].present?
+
+        result
+      end
+
+      # Collects metadata for the timeline entry
+      #
+      # @param meta_config [Hash] The metadata configuration
+      # @param config_key [String] The configuration key for this model
+      # @return [Hash] Collected metadata
+      def collect_metadata(meta_config, config_key)
+        config = self.class.loggers[config_key]
+        metadata = {}
+
+        # First, add any thread-level metadata
+        metadata.merge!(ModelTimeline.metadata)
+
+        # Then, add any model-specific metadata defined in config
+        meta_config.each do |key, value|
+          resolved_value = case value
+                           when Proc
+                             instance_exec(self, &value)
+                           when Symbol
+                             respond_to?(value) ? send(value) : value
+                           else
+                             value
+                           end
+          metadata[key] = resolved_value
+        end
+
+        # Only include keys that exist as columns in the timeline entry table
+        column_names = config[:klass].column_names.map(&:to_sym)
+        metadata.slice(*column_names)
+      end
+  end
+end

data/lib/model_timeline/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ModelTimeline
+  # Current version of the ModelTimeline gem.
+  # Follows semantic versioning (https://semver.org/).
+  #
+  # @return [String] The current version in the format "MAJOR.MINOR.PATCH"
+  VERSION = '0.1.0'
+end