rails_audit_log 0.8.0 → 1.0.0

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.8.0"
+  VERSION = "1.0.0"
 end

data/lib/rails_audit_log.rb

@@ -1,39 +1,153 @@
 require "rails_audit_log/version"
 require "rails_audit_log/engine"
 
+# RailsAuditLog is a Rails engine that tracks ActiveRecord +create+, +update+,
+# and +destroy+ events as {AuditLogEntry} records with JSON-first storage and
+# thread-local actor context.
+#
+# == Quick start
+#
+#   # config/initializers/rails_audit_log.rb
+#   RailsAuditLog.configure do |config|
+#     config.ignored_attributes = %w[updated_at cached_at]
+#     config.store_snapshot      = true
+#     config.async               = false
+#   end
+#
+#   # app/models/article.rb
+#   class Article < ApplicationRecord
+#     include RailsAuditLog::Auditable
+#     audit_log only: %i[title body]
+#   end
+#
+#   # app/controllers/application_controller.rb
+#   class ApplicationController < ActionController::Base
+#     include RailsAuditLog::Controller
+#     audit_log_actor { current_user }
+#   end
 module RailsAuditLog
-  # Global default columns to ignore across all audited models.
-  # Override in an initializer: RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
+  # Columns ignored on every audited model unless overridden with +only:+ or
+  # +ignore:+ on {Auditable.audit_log}.
+  #
+  # @return [Array<String>]
   mattr_accessor :ignored_attributes, default: %w[updated_at]
 
-  def self.configure
-    yield self
-  end
+  # Whether to store a full snapshot of the record's attributes in the +object+
+  # column alongside +object_changes+. Disable to reduce storage at the cost of
+  # losing {AuditLogEntry#reify} fidelity for pre-snapshot entries.
+  #
+  # @return [Boolean]
   mattr_accessor :store_snapshot, default: true
+
+  # When +true+, captures +remote_ip+ and +user_agent+ from the current request
+  # and merges them into every entry's +metadata+ column.
+  # Requires {Controller} to be included in your base controller.
+  #
+  # @return [Boolean]
   mattr_accessor :capture_request_metadata, default: false
+
+  # Global cap on the number of {AuditLogEntry} records kept per tracked object.
+  # Oldest entries are pruned after each write once the limit is exceeded.
+  # Override per-model with <tt>audit_log version_limit: N</tt>.
+  #
+  # @return [Integer, nil]
   mattr_accessor :version_limit, default: nil
+
+  # When +true+, all audit writes are dispatched via +WriteAuditLogJob+ instead
+  # of being written inline. Override per-model with <tt>audit_log async: true</tt>.
+  #
+  # @return [Boolean]
   mattr_accessor :async, default: false
+
+  # Passes +connects_to+ options directly to {AuditLogEntry} so audit entries
+  # can be stored on a separate database.
+  #
+  # @return [Hash, nil]
+  # @example
+  #   RailsAuditLog.connects_to = { database: { writing: :audit_primary } }
   mattr_accessor :connects_to, default: nil
+
+  # Number of entries per page in the web dashboard.
+  #
+  # @return [Integer]
+  mattr_accessor :page_size, default: 25
+
+  # Controls how an actor object is serialised into the +whodunnit_snapshot+
+  # string column. Defaults to +actor.name+ when available, otherwise +to_s+.
+  #
+  # @return [Proc]
+  # @example Store email instead of name
+  #   RailsAuditLog.whodunnit_display = ->(actor) { actor.email }
   mattr_accessor :whodunnit_display, default: ->(actor) {
     actor.respond_to?(:name) ? actor.name.to_s : actor.to_s
   }
 
+  # Yields the module so every +mattr_accessor+ setter is reachable as
+  # <tt>config.setting = value</tt>.
+  #
+  # @yield [RailsAuditLog] the module itself
+  # @return [void]
+  # @example
+  #   RailsAuditLog.configure do |config|
+  #     config.ignored_attributes = %w[updated_at]
+  #     config.async = true
+  #   end
+  def self.configure
+    yield self
+  end
+
+  # Sets or returns the authentication block used to gate the web dashboard.
+  # The block is evaluated in controller context, so controller helpers
+  # (e.g. +current_user+) are available directly.
+  # When the block returns falsy, the engine falls back to HTTP Basic auth.
+  #
+  # @yield block evaluated in controller context; return truthy to allow access
+  # @return [Proc, nil] the stored block, or +nil+ when not configured
+  # @example Require admin access
+  #   RailsAuditLog.authenticate { current_user&.admin? }
+  def self.authenticate(&block)
+    @authenticate = block if block_given?
+    @authenticate
+  end
+
+  # Returns the request metadata hash attached to the current thread.
+  # Populated by {Controller} when {.capture_request_metadata} is +true+.
+  #
+  # @return [Hash, nil]
   def self.request_metadata
     Thread.current[:rails_audit_log_request_metadata]
   end
 
+  # @param value [Hash, nil] metadata hash to store on the current thread
+  # @return [Hash, nil]
   def self.request_metadata=(value)
     Thread.current[:rails_audit_log_request_metadata] = value
   end
 
+  # Returns the actor set on the current thread (e.g. the signed-in user).
+  #
+  # @return [Object, nil]
   def self.actor
     Thread.current[:rails_audit_log_actor]
   end
 
+  # Sets the actor on the current thread. Prefer {.with_actor} for scoped
+  # assignment so the value is always restored.
+  #
+  # @param actor [Object, nil]
+  # @return [Object, nil]
   def self.actor=(actor)
     Thread.current[:rails_audit_log_actor] = actor
   end
 
+  # Sets the actor for the duration of the block, then restores the previous
+  # value. Use this in background jobs and rake tasks.
+  #
+  # @param actor [Object] the actor to set (e.g. a +User+ record)
+  # @yield executes the block with +actor+ as the current actor
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.with_actor(robot_user) { DataImporter.new.run }
   def self.with_actor(actor)
     previous = self.actor
     self.actor = actor
@@ -42,10 +156,20 @@ module RailsAuditLog
     self.actor = previous
   end
 
+  # Returns +true+ when audit logging is active on the current thread.
+  #
+  # @return [Boolean]
   def self.enabled?
     !Thread.current[:rails_audit_log_disabled]
   end
 
+  # Suspends audit logging for the duration of the block on the current thread.
+  # Useful in seeds, factories, and test setup where audit noise is unwanted.
+  #
+  # @yield executes the block with audit logging disabled
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.disable { Post.create!(title: "seed post") }
   def self.disable
     previous = Thread.current[:rails_audit_log_disabled]
     Thread.current[:rails_audit_log_disabled] = true
@@ -54,14 +178,27 @@ module RailsAuditLog
     Thread.current[:rails_audit_log_disabled] = previous
   end
 
+  # Returns the reason string set on the current thread.
+  #
+  # @return [String, nil]
   def self.reason
     Thread.current[:rails_audit_log_reason]
   end
 
+  # @param value [String, nil]
+  # @return [String, nil]
   def self.reason=(value)
     Thread.current[:rails_audit_log_reason] = value
   end
 
+  # Sets a human-readable reason for the changes made within the block.
+  # The reason is stored in each {AuditLogEntry#reason} and restored afterwards.
+  #
+  # @param value [String] reason to attach to every entry written in the block
+  # @yield executes the block with +value+ as the current reason
+  # @return [Object] the return value of the block
+  # @example
+  #   RailsAuditLog.audit_log_reason("bulk import") { records.each(&:save!) }
   def self.audit_log_reason(value)
     previous = self.reason
     self.reason = value
@@ -70,6 +207,18 @@ module RailsAuditLog
     self.reason = previous
   end
 
+  # Collects all {AuditLogEntry} records created within the block and inserts
+  # them with a single <tt>INSERT ... VALUES (…), (…)</tt> via +insert_all!+
+  # instead of one INSERT per record.
+  #
+  # Calls are idempotent: if a batch is already in progress on the current
+  # thread (i.e. a nested call), the inner block joins the outer batch.
+  #
+  # @yield executes the block; any audit entries created are buffered
+  # @return [Object] the return value of the block
+  # @raise [ActiveRecord::RecordInvalid] if any entry fails the +insert_all!+
+  # @example
+  #   RailsAuditLog.batch_audit { 500.times { |i| Post.create!(title: "Post #{i}") } }
   def self.batch_audit
     return yield if Thread.current[:rails_audit_log_batch]
 
@@ -84,10 +233,29 @@ module RailsAuditLog
     end
   end
 
+  # Returns the in-progress batch buffer for the current thread, or +nil+ when
+  # no batch is active.
+  #
+  # @api private
+  # @return [Array<Hash>, nil]
   def self.batch_audit_buffer
     Thread.current[:rails_audit_log_batch]
   end
 
+  # Reconstructs the state of +record+ as it was at +time+ by replaying audit
+  # entries up to that timestamp.
+  #
+  # Returns an unsaved, non-persisted instance of +record.class+ whose
+  # attributes match the record's state at +time+, or +nil+ when no audit
+  # entry exists before +time+ or the record was destroyed at or before +time+.
+  #
+  # @param record [ActiveRecord::Base] the record to reconstruct
+  # @param time [Time] the point in time to reconstruct at
+  # @return [ActiveRecord::Base, nil] a new, unpersisted instance; or +nil+
+  # @example
+  #   post = Post.find(42)
+  #   snapshot = RailsAuditLog.version_at(post, 1.week.ago)
+  #   snapshot.title  # => title as it was a week ago
   def self.version_at(record, time)
     entry = AuditLogEntry
       .where(item_type: record.class.name, item_id: record.id)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -23,9 +23,52 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
-description: A modern Rails engine that tracks ActiveRecord create, update, and destroy
-  events with JSON-first storage, whodunnit actor context, and a clean query API.
-  Drop-in replacement for PaperTrail with no legacy baggage.
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '43.0'
+description: Rails engine that tracks ActiveRecord create, update, and destroy events
+  as structured JSON records. Ships a mountable web dashboard, whodunnit actor context,
+  batch inserts via insert_all!, async writes via ActiveJob, time-travel reconstruction,
+  RSpec matchers, Minitest assertions, and a migration path from PaperTrail.
 email:
 - chuck@eclecticcoding.com
 executables: []
@@ -35,25 +78,47 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/assets/stylesheets/rails_audit_log/_01_base.css
+- app/assets/stylesheets/rails_audit_log/_02_layout.css
+- app/assets/stylesheets/rails_audit_log/_03_table.css
+- app/assets/stylesheets/rails_audit_log/_04_badges.css
+- app/assets/stylesheets/rails_audit_log/_05_diff.css
+- app/assets/stylesheets/rails_audit_log/_06_timeline.css
+- app/assets/stylesheets/rails_audit_log/_07_detail.css
+- app/assets/stylesheets/rails_audit_log/_08_pagination.css
+- app/assets/stylesheets/rails_audit_log/_09_filters.css
 - app/assets/stylesheets/rails_audit_log/application.css
 - app/concerns/rails_audit_log/auditable.rb
 - app/concerns/rails_audit_log/controller.rb
 - app/controllers/rails_audit_log/application_controller.rb
+- app/controllers/rails_audit_log/audit_log_entries_controller.rb
+- app/controllers/rails_audit_log/resources_controller.rb
 - app/helpers/rails_audit_log/application_helper.rb
+- app/javascript/rails_audit_log/application.js
+- app/javascript/rails_audit_log/diff_controller.js
+- app/javascript/rails_audit_log/search_controller.js
 - app/jobs/rails_audit_log/application_job.rb
 - app/jobs/rails_audit_log/write_audit_log_job.rb
 - app/models/rails_audit_log/application_record.rb
 - app/models/rails_audit_log/audit_log_entry.rb
 - app/views/layouts/rails_audit_log/application.html.erb
+- app/views/rails_audit_log/audit_log_entries/_diff.html.erb
+- app/views/rails_audit_log/audit_log_entries/index.html.erb
+- app/views/rails_audit_log/audit_log_entries/show.html.erb
+- app/views/rails_audit_log/resources/show.html.erb
+- config/importmap.rb
 - config/routes.rb
 - lib/generators/rails_audit_log/initializer/initializer_generator.rb
 - lib/generators/rails_audit_log/initializer/templates/rails_audit_log.rb
 - lib/generators/rails_audit_log/install/install_generator.rb
 - lib/generators/rails_audit_log/install/templates/create_audit_log_entries.rb
+- lib/generators/rails_audit_log/migrate_from_paper_trail/migrate_from_paper_trail_generator.rb
+- lib/generators/rails_audit_log/migrate_from_paper_trail/templates/migrate_from_paper_trail.rb
 - lib/rails_audit_log.rb
 - lib/rails_audit_log/engine.rb
 - lib/rails_audit_log/matchers.rb
 - lib/rails_audit_log/minitest_assertions.rb
+- lib/rails_audit_log/paper_trail_compat.rb
 - lib/rails_audit_log/test_helpers.rb
 - lib/rails_audit_log/version.rb
 - lib/tasks/rails_audit_log_tasks.rake
@@ -81,5 +146,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Zeitwerk-native audit logging for ActiveRecord
+summary: Audit logging for Rails with a web dashboard and JSON-first storage
 test_files: []