paper_trail 11.1.0 → 12.3.0

data/lib/paper_trail/version_concern.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require "paper_trail/attribute_serializers/object_changes_attribute"
+require "paper_trail/queries/versions/where_attribute_changes"
 require "paper_trail/queries/versions/where_object"
 require "paper_trail/queries/versions/where_object_changes"
+require "paper_trail/queries/versions/where_object_changes_from"
+require "paper_trail/queries/versions/where_object_changes_to"
 
 module PaperTrail
   # Originally, PaperTrail did not provide this module, and all of this
@@ -13,22 +16,13 @@ module PaperTrail
     extend ::ActiveSupport::Concern
 
     included do
-      if ::ActiveRecord.gem_version >= Gem::Version.new("5.0")
-        belongs_to :item, polymorphic: true, optional: true
-      else
-        belongs_to :item, polymorphic: true
-      end
-
+      belongs_to :item, polymorphic: true, optional: true, inverse_of: false
       validates_presence_of :event
       after_create :enforce_version_limit!
     end
 
     # :nodoc:
     module ClassMethods
-      def item_subtype_column_present?
-        column_names.include?("item_subtype")
-      end
-
       def with_item_keys(item_type, item_id)
         where item_type: item_type, item_id: item_id
       end
@@ -46,7 +40,7 @@ module PaperTrail
       end
 
       def not_creates
-        where "event <> ?", "create"
+        where.not(event: "create")
       end
 
       def between(start_time, end_time)
@@ -64,6 +58,18 @@ module PaperTrail
         end
       end
 
+      # Given an attribute like `"name"`, query the `versions.object_changes`
+      # column for any changes that modified the provided attribute.
+      #
+      # @api public
+      def where_attribute_changes(attribute)
+        unless attribute.is_a?(String) || attribute.is_a?(Symbol)
+          raise ArgumentError, "expected to receive a String or Symbol"
+        end
+
+        Queries::Versions::WhereAttributeChanges.new(self, attribute).execute
+      end
+
       # Given a hash of attributes like `name: 'Joan'`, query the
       # `versions.objects` column.
       #
@@ -120,6 +126,36 @@ module PaperTrail
         Queries::Versions::WhereObjectChanges.new(self, args).execute
       end
 
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # from the hash of attributes to other values.
+      #
+      # This is useful for finding versions where the attribute started with a
+      # known value and changed to something else. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_from(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesFrom.new(self, args).execute
+      end
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # to the hash of attributes from other values.
+      #
+      # This is useful for finding versions where the attribute started with an
+      # unknown value and changed to a known value. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_to(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesTo.new(self, args).execute
+      end
+
       def primary_key_is_int?
         @primary_key_is_int ||= columns_hash[primary_key].type == :integer
       rescue StandardError # TODO: Rescue something more specific
@@ -226,7 +262,7 @@ module PaperTrail
     #
     def reify(options = {})
       unless self.class.column_names.include? "object"
-        raise "reify can't be called without an object column"
+        raise Error, "reify requires an object column"
       end
       return nil if object.nil?
       ::PaperTrail::Reifier.reify(self, options)
@@ -273,7 +309,7 @@ module PaperTrail
 
     # @api private
     def load_changeset
-      if PaperTrail.config.object_changes_adapter&.respond_to?(:load_changeset)
+      if PaperTrail.config.object_changes_adapter.respond_to?(:load_changeset)
         return PaperTrail.config.object_changes_adapter.load_changeset(self)
       end
 
@@ -339,16 +375,23 @@ module PaperTrail
     # The version limit can be global or per-model.
     #
     # @api private
-    #
-    # TODO: Duplication: similar `constantize` in Reifier#version_reification_class
     def version_limit
-      if self.class.item_subtype_column_present?
-        klass = (item_subtype || item_type).constantize
-        if klass&.paper_trail_options&.key?(:limit)
-          return klass.paper_trail_options[:limit]
-        end
+      klass = item.class
+      if limit_option?(klass)
+        klass.paper_trail_options[:limit]
+      elsif base_class_limit_option?(klass)
+        klass.base_class.paper_trail_options[:limit]
+      else
+        PaperTrail.config.version_limit
       end
-      PaperTrail.config.version_limit
+    end
+
+    def limit_option?(klass)
+      klass.respond_to?(:paper_trail_options) && klass.paper_trail_options.key?(:limit)
+    end
+
+    def base_class_limit_option?(klass)
+      klass.respond_to?(:base_class) && limit_option?(klass.base_class)
     end
   end
 end

data/lib/paper_trail/version_number.rb

@@ -7,8 +7,8 @@ module PaperTrail
   # because of this confusion, but it's not worth the breaking change.
   # People are encouraged to use `PaperTrail.gem_version` instead.
   module VERSION
-    MAJOR = 11
-    MINOR = 1
+    MAJOR = 12
+    MINOR = 3
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

data/lib/paper_trail.rb

@@ -8,40 +8,26 @@
 # can revisit this decision.
 require "active_support/all"
 
-# AR is required for, eg. has_paper_trail.rb, so we could put this `require` in
-# all of those files, but it seems easier to troubleshoot if we just make sure
-# AR is loaded here before loading *any* of PT. See discussion of
-# performance/simplicity tradeoff for activesupport above.
-require "active_record"
-
-require "request_store"
+require "paper_trail/errors"
 require "paper_trail/cleaner"
 require "paper_trail/compatibility"
 require "paper_trail/config"
-require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
-require "paper_trail/reifier"
 require "paper_trail/request"
-require "paper_trail/version_concern"
 require "paper_trail/version_number"
 require "paper_trail/serializers/json"
-require "paper_trail/serializers/yaml"
 
 # An ActiveRecord extension that tracks changes to your models, for auditing or
 # versioning.
 module PaperTrail
-  E_RAILS_NOT_LOADED = <<-EOS.squish.freeze
-    PaperTrail has been loaded too early, before rails is loaded. This can
-    happen when another gem defines the ::Rails namespace, then PT is loaded,
-    all before rails is loaded. You may want to reorder your Gemfile, or defer
-    the loading of PT by using `require: false` and a manual require elsewhere.
-  EOS
   E_TIMESTAMP_FIELD_CONFIG = <<-EOS.squish.freeze
     PaperTrail.timestamp_field= has been removed, without replacement. It is no
     longer configurable. The timestamp column in the versions table must now be
     named created_at.
   EOS
 
+  RAILS_GTE_7_0 = ::ActiveRecord.gem_version >= ::Gem::Version.new("7.0.0")
+
   extend PaperTrail::Cleaner
 
   class << self
@@ -85,7 +71,7 @@ module PaperTrail
     #
     # @api public
     def request(options = nil, &block)
-      if options.nil? && !block_given?
+      if options.nil? && !block
         Request
       else
         Request.with(options, &block)
@@ -95,7 +81,7 @@ module PaperTrail
     # Set the field which records when a version was created.
     # @api public
     def timestamp_field=(_field_name)
-      raise(E_TIMESTAMP_FIELD_CONFIG)
+      raise Error, E_TIMESTAMP_FIELD_CONFIG
     end
 
     # Set the PaperTrail serializer. This setting affects all threads.
@@ -126,27 +112,18 @@ module PaperTrail
   end
 end
 
-# We use the `on_load` "hook" instead of `ActiveRecord::Base.include` because we
-# don't want to cause all of AR to be autloaded yet. See
-# https://guides.rubyonrails.org/engines.html#what-are-on-load-hooks-questionmark
-# to learn more about `on_load`.
-ActiveSupport.on_load(:active_record) do
-  include PaperTrail::Model
-end
-
-# Require frameworks
-if defined?(::Rails)
-  # Rails module is sometimes defined by gems like rails-html-sanitizer
-  # so we check for presence of Rails.application.
-  if defined?(::Rails.application)
-    require "paper_trail/frameworks/rails"
-  else
-    ::Kernel.warn(::PaperTrail::E_RAILS_NOT_LOADED)
-  end
+# PT is built on ActiveRecord, but does not require Rails. If Rails is defined,
+# our Railtie makes sure not to load the AR-dependent parts of PT until AR is
+# ready. A typical Rails `application.rb` has:
+#
+# ```
+# require 'rails/all' # Defines `Rails`
+# Bundler.require(*Rails.groups) # require 'paper_trail' (this file)
+# ```
+#
+# Non-rails applications should take similar care to load AR before PT.
+if defined?(Rails)
+  require "paper_trail/frameworks/rails"
 else
   require "paper_trail/frameworks/active_record"
 end
-
-if defined?(::ActiveRecord)
-  ::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail
 version: !ruby/object:Gem::Version
-  version: 11.1.0
+  version: 12.3.0
 platform: ruby
 authors:
 - Andy Stewart
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-16 00:00:00.000000000 Z
+date: 2022-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -46,42 +46,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.4.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.4.1
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '11.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.0'
+        version: '11.1'
 - !ruby/object:Gem::Dependency
   name: ffaker
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.11'
+        version: '2.20'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.11'
+        version: '2.20'
 - !ruby/object:Gem::Dependency
   name: generator_spec
   requirement: !ruby/object:Gem::Requirement
@@ -102,14 +102,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 1.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -144,90 +144,140 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.0.2
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.89.1
+        version: 1.22.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.89.1
+        version: 1.22.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-packaging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.1
+        version: 1.11.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.5
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.12.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.12.4
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.1
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.42.0
+        version: 2.5.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.42.0
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
 - !ruby/object:Gem::Dependency
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.5.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.5.3
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.18'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -251,7 +301,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
 - LICENSE
 - lib/generators/paper_trail/install/USAGE
 - lib/generators/paper_trail/install/install_generator.rb
@@ -270,6 +319,7 @@ files:
 - lib/paper_trail/cleaner.rb
 - lib/paper_trail/compatibility.rb
 - lib/paper_trail/config.rb
+- lib/paper_trail/errors.rb
 - lib/paper_trail/events/base.rb
 - lib/paper_trail/events/create.rb
 - lib/paper_trail/events/destroy.rb
@@ -279,13 +329,16 @@ files:
 - lib/paper_trail/frameworks/cucumber.rb
 - lib/paper_trail/frameworks/rails.rb
 - lib/paper_trail/frameworks/rails/controller.rb
-- lib/paper_trail/frameworks/rails/engine.rb
+- lib/paper_trail/frameworks/rails/railtie.rb
 - lib/paper_trail/frameworks/rspec.rb
 - lib/paper_trail/frameworks/rspec/helpers.rb
 - lib/paper_trail/has_paper_trail.rb
 - lib/paper_trail/model_config.rb
+- lib/paper_trail/queries/versions/where_attribute_changes.rb
 - lib/paper_trail/queries/versions/where_object.rb
 - lib/paper_trail/queries/versions/where_object_changes.rb
+- lib/paper_trail/queries/versions/where_object_changes_from.rb
+- lib/paper_trail/queries/versions/where_object_changes_to.rb
 - lib/paper_trail/record_history.rb
 - lib/paper_trail/record_trail.rb
 - lib/paper_trail/reifier.rb
@@ -295,7 +348,6 @@ files:
 - lib/paper_trail/type_serializers/postgres_array_serializer.rb
 - lib/paper_trail/version_concern.rb
 - lib/paper_trail/version_number.rb
-- paper_trail.gemspec
 homepage: https://github.com/paper-trail-gem/paper_trail
 licenses:
 - MIT
@@ -308,14 +360,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
 summary: Track changes to your models.

data/Gemfile

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-gemspec

data/lib/paper_trail/frameworks/rails/engine.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module PaperTrail
-  module Rails
-    # See http://guides.rubyonrails.org/engines.html
-    class Engine < ::Rails::Engine
-      DPR_CONFIG_ENABLED = <<~EOS.squish.freeze
-        The rails configuration option config.paper_trail.enabled is deprecated.
-        Please use PaperTrail.enabled= instead. People were getting confused
-        that PT has both, specifically regarding *when* each was happening. If
-        you'd like to keep config.paper_trail, join the discussion at
-        https://github.com/paper-trail-gem/paper_trail/pull/1176
-      EOS
-      private_constant :DPR_CONFIG_ENABLED
-      DPR_RUDELY_ENABLING = <<~EOS.squish.freeze
-        At some point early in the rails boot process, you have set
-        PaperTrail.enabled = false. PT's rails engine is now overriding your
-        setting, and setting it to true. We're not sure why, but this is how PT
-        has worked since 5.0, when the config.paper_trail.enabled option was
-        introduced. This is now deprecated. In the future, PT will not override
-        your setting. See
-        https://github.com/paper-trail-gem/paper_trail/pull/1176 for discussion.
-      EOS
-      private_constant :DPR_RUDELY_ENABLING
-
-      paths["app/models"] << "lib/paper_trail/frameworks/active_record/models"
-
-      # --- Begin deprecated section ---
-      config.paper_trail = ActiveSupport::OrderedOptions.new
-      initializer "paper_trail.initialisation" do |app|
-        enable = app.config.paper_trail[:enabled]
-        if enable.nil?
-          unless PaperTrail.enabled?
-            ::ActiveSupport::Deprecation.warn(DPR_RUDELY_ENABLING)
-            PaperTrail.enabled = true
-          end
-        else
-          ::ActiveSupport::Deprecation.warn(DPR_CONFIG_ENABLED)
-          PaperTrail.enabled = enable
-        end
-      end
-      # --- End deprecated section ---
-    end
-  end
-end

data/paper_trail.gemspec

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift File.expand_path("lib", __dir__)
-require "paper_trail/compatibility"
-require "paper_trail/version_number"
-
-Gem::Specification.new do |s|
-  s.name = "paper_trail"
-  s.version = PaperTrail::VERSION::STRING
-  s.platform = Gem::Platform::RUBY
-  s.summary = "Track changes to your models."
-  s.description = <<-EOS
-Track changes to your models, for auditing or versioning. See how a model looked
-at any stage in its lifecycle, revert it to any version, or restore it after it
-has been destroyed.
-  EOS
-  s.homepage = "https://github.com/paper-trail-gem/paper_trail"
-  s.authors = ["Andy Stewart", "Ben Atkins", "Jared Beck"]
-  s.email = "jared@jaredbeck.com"
-  s.license = "MIT"
-
-  s.files = `git ls-files -z`.split("\x0").select { |f|
-    f.match(%r{^(Gemfile|LICENSE|lib/|paper_trail.gemspec)})
-  }
-  s.executables = []
-  s.require_paths = ["lib"]
-
-  s.required_rubygems_version = ">= 1.3.6"
-
-  # Ruby 2.4 reaches EoL at the end of March of 2020
-  # https://www.ruby-lang.org/en/news/2019/10/02/ruby-2-4-9-released/
-  s.required_ruby_version = ">= 2.4.0"
-
-  # We no longer specify a maximum activerecord version.
-  # See discussion in paper_trail/compatibility.rb
-  s.add_dependency "activerecord", ::PaperTrail::Compatibility::ACTIVERECORD_GTE
-  s.add_dependency "request_store", "~> 1.1"
-
-  s.add_development_dependency "appraisal", "~> 2.2"
-  s.add_development_dependency "byebug", "~> 11.0"
-  s.add_development_dependency "ffaker", "~> 2.11"
-  s.add_development_dependency "generator_spec", "~> 0.9.4"
-  s.add_development_dependency "memory_profiler", "~> 0.9.14"
-
-  # For `spec/dummy_app`. Technically, we only need `actionpack` (as of 2020).
-  # However, that might change in the future, and the advantages of specifying a
-  # subset (e.g. actionpack only) are unclear.
-  s.add_development_dependency "rails", ::PaperTrail::Compatibility::ACTIVERECORD_GTE
-
-  s.add_development_dependency "rake", "~> 13.0"
-  s.add_development_dependency "rspec-rails", "~> 4.0"
-  s.add_development_dependency "rubocop", "~> 0.89.1"
-  s.add_development_dependency "rubocop-performance", "~> 1.7.1"
-  s.add_development_dependency "rubocop-rspec", "~> 1.42.0"
-
-  # ## Database Adapters
-  #
-  # The dependencies here must match the `gem` call at the top of their
-  # adapters, eg. `active_record/connection_adapters/mysql2_adapter.rb`,
-  # assuming said call is consistent for all versions of rails we test against
-  # (see `Appraisals`).
-  #
-  # Currently, all versions of rails we test against are consistent. In the past,
-  # when we tested against rails 4.2, we had to specify database adapters in
-  # `Appraisals`.
-  s.add_development_dependency "mysql2", "~> 0.5"
-  s.add_development_dependency "pg", ">= 0.18", "< 2.0"
-  s.add_development_dependency "sqlite3", "~> 1.4"
-end