rails_audit_log 0.9.0 → 1.0.0

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -1,4 +1,23 @@
 module RailsAuditLog
+  # Represents a single audited event (+create+, +update+, or +destroy+) for
+  # one ActiveRecord record.
+  #
+  # == Columns
+  #
+  # [event]               One of <tt>"create"</tt>, <tt>"update"</tt>, <tt>"destroy"</tt>.
+  # [item_type]           Class name of the audited record (e.g. <tt>"Article"</tt>).
+  # [item_id]             Primary key of the audited record.
+  # [object_changes]      JSON hash of attribute changes in <tt>[from, to]</tt> form.
+  #                       All three event types use the same format:
+  #                       +create+ stores <tt>[nil, new]</tt> for every column,
+  #                       +update+ stores <tt>[old, new]</tt> for changed columns only,
+  #                       +destroy+ stores <tt>[final, nil]</tt> for every column.
+  # [object]              JSON snapshot of the record's full attributes before the
+  #                       change (stored when {RailsAuditLog.store_snapshot} is +true+).
+  # [whodunnit_snapshot]  Display name of the actor at the time of the change.
+  # [actor_type / actor_id] Polymorphic reference to the actor record.
+  # [reason]              Optional free-text reason string.
+  # [metadata]            Arbitrary JSON hash (request IP, custom lambdas, etc.).
   class AuditLogEntry < ApplicationRecord
     self.table_name = "audit_log_entries"
 
@@ -6,33 +25,63 @@ module RailsAuditLog
     BLOB_COLUMNS = %w[object_changes object metadata].freeze
     PERIODS      = { "1h" => 1.hour, "24h" => 24.hours, "7d" => 7.days }.freeze
 
+    # @api private
     def self.configure_connection!
       return unless (opts = RailsAuditLog.connects_to)
 
       connects_to(**opts)
     end
 
-    belongs_to :item, polymorphic: true, optional: true
+    belongs_to :item,  polymorphic: true, optional: true
     belongs_to :actor, polymorphic: true, optional: true
 
-    validates :event, presence: true, inclusion: { in: EVENTS }
+    validates :event,     presence: true, inclusion: { in: EVENTS }
     validates :item_type, presence: true
-    validates :item_id, presence: true
-    validate :metadata_must_be_a_hash
+    validates :item_id,   presence: true
+    validate  :metadata_must_be_a_hash
 
-    # Event scopes
+    # @!group Event scopes
+
+    # Entries for +create+ events.
+    # @return [ActiveRecord::Relation]
     scope :created_events,  -> { where(event: "create") }
+
+    # Entries for +update+ events.
+    # @return [ActiveRecord::Relation]
     scope :updated_events,  -> { where(event: "update") }
-    scope :destroyed_events, -> { where(event: "destroy") }
 
-    # Deprecated short aliases kept for backwards compatibility
+    # Entries for +destroy+ events.
+    # @return [ActiveRecord::Relation]
+    scope :destroyed_events, -> { where(event: "destroy") }
 
+    # @deprecated Use {.created_events} instead.
     scope :creates,  -> { created_events }
+    # @deprecated Use {.updated_events} instead.
     scope :updates,  -> { updated_events }
+    # @deprecated Use {.destroyed_events} instead.
     scope :destroys, -> { destroyed_events }
 
-    # Actor / resource scopes
+    # @!endgroup
+
+    # @!group Actor / resource scopes
+
+    # Entries written by a specific actor.
+    #
+    # @param actor [ActiveRecord::Base] the actor record to filter by
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.by_actor(current_user)
     scope :by_actor, ->(actor) { where(actor_type: actor.class.name, actor_id: actor.id) }
+
+    # Entries for a specific resource class or instance.
+    # Pass a class to get all entries for that type; pass an instance for one record.
+    #
+    # @param resource [Class, ActiveRecord::Base]
+    # @return [ActiveRecord::Relation]
+    # @example All entries for Article
+    #   AuditLogEntry.for_resource(Article)
+    # @example All entries for one article
+    #   AuditLogEntry.for_resource(article)
     scope :for_resource, lambda { |resource|
       if resource.is_a?(Class)
         where(item_type: resource.name)
@@ -41,16 +90,61 @@ module RailsAuditLog
       end
     }
 
-    # Time scopes
-    scope :since,      ->(time)   { where(created_at: time..) }
-    scope :until,      ->(time)   { where(created_at: ..time) }
+    # @!endgroup
+
+    # @!group Time scopes
+
+    # Entries created at or after +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
+    scope :since, ->(time) { where(created_at: time..) }
+
+    # Entries created at or before +time+.
+    #
+    # @param time [Time]
+    # @return [ActiveRecord::Relation]
+    scope :until, ->(time) { where(created_at: ..time) }
+
+    # Entries within a named period. Valid keys: <tt>"1h"</tt>, <tt>"24h"</tt>, <tt>"7d"</tt>.
+    #
+    # @param period [String] one of +PERIODS.keys+
+    # @return [ActiveRecord::Relation]
     scope :for_period, ->(period) { where(created_at: PERIODS[period].ago..) }
 
-    # Projection scope — omits JSON blob columns for index/listing queries
+    # @!endgroup
+
+    # Omits the three JSON blob columns (+object_changes+, +object+, +metadata+)
+    # from the +SELECT+. Use on index/listing queries where blobs are not
+    # displayed to reduce I/O and avoid deserializing large payloads.
+    #
+    # @return [ActiveRecord::Relation]
     scope :slim, -> { select(column_names - BLOB_COLUMNS) }
 
-    # Instance methods
+    # Entries where +object_changes+ contains a key matching +attribute+.
+    # Uses <tt>json_extract</tt> on SQLite/MySQL and <tt>->></tt> on PostgreSQL.
+    #
+    # @param attribute [Symbol, String] the attribute name to filter on
+    # @return [ActiveRecord::Relation]
+    # @example
+    #   AuditLogEntry.touching(:title)
+    #   post.audit_log_entries.updated_events.touching(:published_at)
+    scope :touching, ->(attribute) {
+      if connection.adapter_name =~ /PostgreSQL/i
+        # :nocov:
+        where("object_changes->>? IS NOT NULL", attribute.to_s)
+        # :nocov:
+      else
+        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
+      end
+    }
 
+    # Reconstructs and returns the record's state *before* this entry's change.
+    # Uses the +object+ snapshot when available; falls back to deriving prior
+    # state from +object_changes+ (or the live record for +update+ entries).
+    #
+    # @return [ActiveRecord::Base, nil] an unpersisted instance; +nil+ for
+    #   +create+ entries (there is no prior state)
     def reify
       return nil if event == "create"
 
@@ -82,18 +176,37 @@ module RailsAuditLog
       instance
     end
 
+    # Returns the entry immediately before this one in the version chain for
+    # the same record (lower +id+), or +nil+ if this is the first entry.
+    #
+    # @return [AuditLogEntry, nil]
     def previous
       self.class.where(item_type: item_type, item_id: item_id).where("id < ?", id).order(id: :desc).first
     end
 
+    # Returns the entry immediately after this one in the version chain for
+    # the same record (higher +id+), or +nil+ if this is the last entry.
+    #
+    # @return [AuditLogEntry, nil]
     def next
       self.class.where(item_type: item_type, item_id: item_id).where("id > ?", id).order(id: :asc).first
     end
 
+    # Returns the list of attribute (and association) names that changed in
+    # this entry, derived from the keys of +object_changes+.
+    #
+    # @return [Array<String>]
     def changed_attributes
       object_changes&.keys || []
     end
 
+    # Returns +object_changes+ in a named-key format convenient for display.
+    #
+    # @return [Hash{String => Hash}] keys are attribute names; values are
+    #   hashes with +:from+ and +:to+ keys
+    # @example
+    #   entry.diff
+    #   # => { "title" => { from: "Old", to: "New" }, ... }
     def diff
       return {} unless object_changes
 
@@ -105,18 +218,5 @@ module RailsAuditLog
     def metadata_must_be_a_hash
       errors.add(:metadata, "must be a Hash") if metadata.present? && !metadata.is_a?(Hash)
     end
-
-    public
-
-    # Attribute scope — uses json_extract (SQLite/MySQL) or ->> (PostgreSQL)
-    scope :touching, ->(attribute) {
-      if connection.adapter_name =~ /PostgreSQL/i
-        # :nocov:
-        where("object_changes->>? IS NOT NULL", attribute.to_s)
-        # :nocov:
-      else
-        where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")
-      end
-    }
   end
 end

data/lib/generators/rails_audit_log/migrate_from_paper_trail/migrate_from_paper_trail_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsAuditLog
+  module Generators
+    class MigrateFromPaperTrailGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a data migration that copies PaperTrail versions to audit_log_entries."
+
+      def create_migration_file
+        migration_template(
+          "migrate_from_paper_trail.rb",
+          "db/migrate/migrate_from_paper_trail.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/rails_audit_log/migrate_from_paper_trail/templates/migrate_from_paper_trail.rb

@@ -0,0 +1,99 @@
+require "yaml"
+require "json"
+
+# Data migration: copies PaperTrail `versions` rows to `audit_log_entries`.
+#
+# Column mapping:
+#   versions.item_type        → audit_log_entries.item_type
+#   versions.item_id          → audit_log_entries.item_id
+#   versions.event            → audit_log_entries.event  (create/update/destroy only)
+#   versions.object_changes   → audit_log_entries.object_changes  (YAML or JSON → JSON)
+#   versions.object           → audit_log_entries.object           (YAML or JSON → JSON)
+#   versions.whodunnit        → audit_log_entries.whodunnit_snapshot
+#   versions.created_at       → audit_log_entries.created_at
+#
+# actor_type / actor_id are not populated — PaperTrail stores the actor
+# only as a string (whodunnit), so polymorphic references cannot be inferred.
+#
+# This migration is irreversible.
+class MigrateFromPaperTrail < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  BATCH_SIZE    = 1_000
+  VALID_EVENTS  = %w[create update destroy].freeze
+
+  # Isolated AR classes to avoid coupling to the host app's models.
+  class Version < ActiveRecord::Base   # @api private
+    self.table_name = "versions"
+  end
+
+  class AuditEntry < ActiveRecord::Base   # @api private
+    self.table_name = "audit_log_entries"
+  end
+
+  def up
+    unless table_exists?(:versions)
+      say "  versions table not found — nothing to migrate."
+      return
+    end
+
+    total     = Version.count
+    migrated  = 0
+    skipped   = 0
+
+    say_with_time "Migrating #{total} PaperTrail versions → audit_log_entries" do
+      Version.in_batches(of: BATCH_SIZE) do |batch|
+        rows = batch.filter_map do |v|
+          next unless VALID_EVENTS.include?(v.event)
+
+          {
+            event:              v.event,
+            item_type:          v.item_type,
+            item_id:            v.item_id,
+            object_changes:     parse_serialized(v.read_attribute_before_type_cast(:object_changes)),
+            object:             parse_serialized(v.read_attribute_before_type_cast(:object)),
+            whodunnit_snapshot: v.whodunnit,
+            created_at:         v.created_at,
+            updated_at:         v.created_at
+          }
+        end
+
+        skipped  += batch.size - rows.size
+        migrated += rows.size
+        AuditEntry.insert_all(rows) if rows.any?
+      end
+    end
+
+    say "  Migrated: #{migrated}  Skipped (unsupported event): #{skipped}"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "Cannot reverse PaperTrail migration — rows already written to audit_log_entries " \
+          "cannot be reliably distinguished from native entries."
+  end
+
+  private
+
+  # Parses a PaperTrail serialized column (YAML or JSON) and returns a Hash,
+  # or nil if the value is blank or unparseable.
+  def parse_serialized(value)
+    return nil if value.nil? || value.to_s.strip.empty?
+
+    begin
+      parsed = JSON.parse(value)
+      return parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      # fall through to YAML
+    end
+
+    begin
+      parsed = YAML.safe_load(
+        value,
+        permitted_classes: [Symbol, Date, Time, DateTime, BigDecimal,
+                             ActiveSupport::TimeWithZone, ActiveSupport::Duration]
+      )
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/rails_audit_log/engine.rb

@@ -4,6 +4,7 @@ require "pagy"
 require "pagy/toolbox/paginators/method"
 
 module RailsAuditLog
+  # @api private
   class Engine < ::Rails::Engine
     isolate_namespace RailsAuditLog
 

data/lib/rails_audit_log/matchers.rb

@@ -1,24 +1,67 @@
 module RailsAuditLog
+  # RSpec matchers for asserting audit log behaviour.
+  #
+  # == Setup
+  #
+  #   # spec/rails_helper.rb
+  #   require "rails_audit_log/matchers"
+  #
+  #   RSpec.configure do |config|
+  #     config.include RailsAuditLog::Matchers
+  #   end
+  #
+  # == Usage
+  #
+  #   # Assert a record already has an entry
+  #   expect(post).to have_audit_log_entry(:update).touching(:title)
+  #
+  #   # Assert a block creates a new entry
+  #   expect { post.update!(title: "New") }.to create_audit_log_entry(event: :update, touching: :title)
   module Matchers
+    # Returns a matcher that asserts the record has at least one matching
+    # {AuditLogEntry}.
+    #
+    # @param event [Symbol, String, nil] optional event filter
+    #   (<tt>:create</tt>, <tt>:update</tt>, or <tt>:destroy</tt>)
+    # @return [HaveAuditLogEntry]
+    # @example
+    #   expect(post).to have_audit_log_entry
+    #   expect(post).to have_audit_log_entry(:update)
+    #   expect(post).to have_audit_log_entry(:update).touching(:title)
     def have_audit_log_entry(event = nil)
       HaveAuditLogEntry.new(event)
     end
 
+    # Returns a matcher that asserts the block creates at least one new
+    # {AuditLogEntry} matching the given filters.
+    #
+    # @param event [Symbol, String, nil] optional event filter
+    # @param touching [Symbol, String, nil] optional attribute filter
+    # @return [CreateAuditLogEntry]
+    # @example
+    #   expect { post.update!(title: "x") }.to create_audit_log_entry(event: :update)
+    #   expect { post.update!(title: "x") }.to create_audit_log_entry(touching: :title)
     def create_audit_log_entry(event: nil, touching: nil)
       CreateAuditLogEntry.new(event: event, touching: touching)
     end
 
+    # RSpec matcher — asserts that a record already has a matching entry.
     class HaveAuditLogEntry
       def initialize(event)
         @event    = event
         @touching = nil
       end
 
+      # Chains an attribute filter onto the matcher.
+      #
+      # @param attribute [Symbol, String]
+      # @return [self]
       def touching(attribute)
         @touching = attribute
         self
       end
 
+      # @api private
       def matches?(record)
         @record = record
         scope = record.audit_log_entries
@@ -27,14 +70,17 @@ module RailsAuditLog
         scope.exists?
       end
 
+      # @api private
       def failure_message
         "expected #{@record.class}##{@record.id} to have an audit log entry#{qualifier}"
       end
 
+      # @api private
       def failure_message_when_negated
         "expected #{@record.class}##{@record.id} not to have an audit log entry#{qualifier}"
       end
 
+      # @api private
       def description
         "have an audit log entry#{qualifier}"
       end
@@ -49,21 +95,28 @@ module RailsAuditLog
       end
     end
 
+    # RSpec matcher — asserts that a block creates a new matching entry.
     class CreateAuditLogEntry
       def initialize(event:, touching:)
         @event    = event
         @touching = touching
       end
 
+      # Chains an attribute filter onto the matcher.
+      #
+      # @param attribute [Symbol, String]
+      # @return [self]
       def touching(attribute)
         @touching = attribute
         self
       end
 
+      # @api private
       def supports_block_expectations?
         true
       end
 
+      # @api private
       def matches?(block)
         @before = matching_scope.count
         block.call
@@ -71,14 +124,17 @@ module RailsAuditLog
         @after > @before
       end
 
+      # @api private
       def failure_message
         "expected block to create an audit log entry#{qualifier}, but none was created"
       end
 
+      # @api private
       def failure_message_when_negated
         "expected block not to create an audit log entry#{qualifier}, but one was created"
       end
 
+      # @api private
       def description
         "create an audit log entry#{qualifier}"
       end

data/lib/rails_audit_log/minitest_assertions.rb

@@ -1,11 +1,47 @@
 module RailsAuditLog
+  # Opt-in Minitest assertions for audit log expectations.
+  #
+  # == Setup
+  #
+  #   # test/test_helper.rb
+  #   require "rails_audit_log/minitest_assertions"
+  #
+  #   class ActiveSupport::TestCase
+  #     include RailsAuditLog::MinitestAssertions
+  #   end
+  #
+  # == Usage
+  #
+  #   assert_audit_log_entry(post, event: :update, touching: :title)
+  #   refute_audit_log_entry(post, event: :create)
   module MinitestAssertions
+    # Asserts that +record+ has at least one {AuditLogEntry} matching the
+    # given filters. Fails with a descriptive message when no entry is found.
+    #
+    # @param record [ActiveRecord::Base] the audited record to check
+    # @param event [Symbol, String, nil] optional event filter
+    #   (<tt>:create</tt>, <tt>:update</tt>, or <tt>:destroy</tt>)
+    # @param touching [Symbol, String, nil] optional attribute name filter
+    # @param message [String, nil] custom failure message; auto-generated when nil
+    # @return [void]
+    # @example
+    #   assert_audit_log_entry(post, event: :update, touching: :title)
     def assert_audit_log_entry(record, event: nil, touching: nil, message: nil)
       scope = build_scope(record, event, touching)
       msg   = message || default_message("to have", record, event, touching)
       assert scope.exists?, msg
     end
 
+    # Asserts that +record+ has *no* {AuditLogEntry} matching the given filters.
+    # Fails with a descriptive message when a matching entry is found.
+    #
+    # @param record [ActiveRecord::Base] the audited record to check
+    # @param event [Symbol, String, nil] optional event filter
+    # @param touching [Symbol, String, nil] optional attribute name filter
+    # @param message [String, nil] custom failure message; auto-generated when nil
+    # @return [void]
+    # @example
+    #   refute_audit_log_entry(post, event: :destroy)
     def refute_audit_log_entry(record, event: nil, touching: nil, message: nil)
       scope = build_scope(record, event, touching)
       msg   = message || default_message("not to have", record, event, touching)

data/lib/rails_audit_log/paper_trail_compat.rb

@@ -0,0 +1,76 @@
+module RailsAuditLog
+  # Opt-in compatibility shim for gradual migration from PaperTrail.
+  # Include alongside RailsAuditLog::Auditable to keep PaperTrail's
+  # familiar API while your codebase migrates.
+  #
+  # @example
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #     include RailsAuditLog::PaperTrailCompat
+  #   end
+  #
+  #   article.versions                         # audit_log_entries, oldest-first
+  #   article.paper_trail.version              # most recent AuditLogEntry
+  #   article.paper_trail.previous_version     # reconstructed previous state
+  #   article.paper_trail.originator           # whodunnit_snapshot string
+  #   article.paper_trail.version_at(1.week.ago) # time-travel reconstruction
+  module PaperTrailCompat
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :versions,
+               -> { order(created_at: :asc, id: :asc) },
+               class_name: "RailsAuditLog::AuditLogEntry",
+               as:         :item,
+               dependent:  :destroy
+    end
+
+    # Returns a proxy object exposing PaperTrail's instance-level API.
+    #
+    # @return [Proxy]
+    def paper_trail
+      @paper_trail_proxy ||= Proxy.new(self)
+    end
+
+    # Proxy providing the PaperTrail instance API surface backed by
+    # {AuditLogEntry} records.
+    class Proxy
+      # @param record [ActiveRecord::Base] the record this proxy wraps
+      def initialize(record)
+        @record = record
+      end
+
+      # The most recent {AuditLogEntry} for the record.
+      #
+      # @return [AuditLogEntry, nil]
+      def version
+        @record.audit_log_entries.order(id: :desc).first
+      end
+
+      # Reconstructs the record's state before the most recent change.
+      # Returns +nil+ for newly created records (no prior state exists).
+      #
+      # @return [ActiveRecord::Base, nil] an unpersisted instance; or +nil+
+      def previous_version
+        version&.reify
+      end
+
+      # Display name of the actor who made the most recent change, as stored
+      # in +whodunnit_snapshot+.
+      #
+      # @return [String, nil]
+      def originator
+        version&.whodunnit_snapshot
+      end
+
+      # Reconstructs the record's state as it was at +timestamp+.
+      # Delegates to {RailsAuditLog.version_at}.
+      #
+      # @param timestamp [Time]
+      # @return [ActiveRecord::Base, nil] an unpersisted instance; or +nil+
+      def version_at(timestamp)
+        RailsAuditLog.version_at(@record, timestamp)
+      end
+    end
+  end
+end

data/lib/rails_audit_log/test_helpers.rb

@@ -1,5 +1,25 @@
 module RailsAuditLog
+  # Opt-in test helper for suppressing audit writes in test setup code.
+  #
+  # == Setup
+  #
+  #   # spec/rails_helper.rb
+  #   require "rails_audit_log/test_helpers"
+  #
+  #   RSpec.configure do |config|
+  #     config.include RailsAuditLog::TestHelpers
+  #   end
+  #
+  # == Usage
+  #
+  #   let(:post) { without_audit_log { Post.create!(title: "fixture") } }
   module TestHelpers
+    # Executes the block with audit logging disabled. A prefix-free wrapper
+    # around {RailsAuditLog.disable} intended for use in FactoryBot factories,
+    # +let+ blocks, and other test setup where audit noise is unwanted.
+    #
+    # @yield executes the block without recording any audit entries
+    # @return [Object] the return value of the block
     def without_audit_log(&block)
       RailsAuditLog.disable(&block)
     end

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "0.9.0"
+  VERSION = "1.0.0"
 end