rails_audit_log 0.8.0 → 1.0.0

data/app/assets/stylesheets/rails_audit_log/_05_diff.css

@@ -0,0 +1,94 @@
+/* Toggle */
+.ral-diff-toggle {
+  display: flex;
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  overflow: hidden;
+  width: fit-content;
+  margin-bottom: 12px;
+}
+
+.ral-diff-btn {
+  padding: 4px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--ral-muted);
+  background: var(--ral-surface);
+  border: none;
+  cursor: pointer;
+}
+.ral-diff-btn + .ral-diff-btn  { border-left: 1px solid var(--ral-border); }
+.ral-diff-btn:hover:not(.ral-diff-btn--active) { background: var(--ral-bg); color: var(--ral-text); }
+.ral-diff-btn--active { background: var(--ral-primary); color: #fff; }
+
+/* Inline table */
+.ral-diff { width: 100%; border-collapse: collapse; font-size: 13px; }
+
+.ral-diff th {
+  background: var(--ral-bg);
+  padding: 6px 12px;
+  text-align: left;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--ral-muted);
+  border-bottom: 1px solid var(--ral-border);
+}
+
+.ral-diff td { padding: 6px 12px; border-bottom: 1px solid var(--ral-border-subtle); vertical-align: top; }
+.ral-diff tbody tr:last-child td { border-bottom: none; }
+
+.ral-diff__attr   { font-weight: 500; color: #333; width: 160px; }
+.ral-diff__before { color: var(--ral-danger);  background: #fff5f5; font-family: monospace; }
+.ral-diff__after  { color: var(--ral-success); background: #f0fdf4; font-family: monospace; }
+
+/* Side-by-side panels */
+.ral-diff-side {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  overflow: hidden;
+  font-size: 13px;
+}
+
+.ral-diff-side__panel--before { border-right: 1px solid var(--ral-border); }
+
+.ral-diff-side__header {
+  padding: 6px 12px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--ral-muted);
+  border-bottom: 1px solid var(--ral-border);
+  background: var(--ral-bg);
+}
+
+.ral-diff-side__row {
+  display: flex;
+  gap: 8px;
+  padding: 6px 12px;
+  border-bottom: 1px solid var(--ral-border-subtle);
+  align-items: baseline;
+}
+.ral-diff-side__row:last-child { border-bottom: none; }
+
+.ral-diff-side__attr  { font-weight: 500; color: #333; min-width: 100px; flex-shrink: 0; }
+
+.ral-diff-side__panel--before .ral-diff-side__value {
+  color: var(--ral-danger);
+  font-family: monospace;
+  background: #fff5f5;
+  padding: 1px 4px;
+  border-radius: 3px;
+}
+
+.ral-diff-side__panel--after .ral-diff-side__value {
+  color: var(--ral-success);
+  font-family: monospace;
+  background: #f0fdf4;
+  padding: 1px 4px;
+  border-radius: 3px;
+}

data/app/assets/stylesheets/rails_audit_log/_06_timeline.css

@@ -0,0 +1,21 @@
+.ral-timeline { display: flex; flex-direction: column; gap: 16px; }
+
+.ral-timeline__entry {
+  background: var(--ral-surface);
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  overflow: hidden;
+  box-shadow: var(--ral-shadow);
+}
+
+.ral-timeline__header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 16px;
+  background: var(--ral-bg);
+  border-bottom: 1px solid var(--ral-border);
+  font-size: 13px;
+}
+
+.ral-timeline__detail-link { margin-left: auto; }

data/app/assets/stylesheets/rails_audit_log/_07_detail.css

@@ -0,0 +1,15 @@
+.ral-card {
+  background: var(--ral-surface);
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  padding: 16px;
+  margin-bottom: 20px;
+  box-shadow: var(--ral-shadow);
+}
+
+.ral-meta { display: grid; gap: 8px; }
+.ral-meta__row { display: flex; gap: 16px; font-size: 13px; }
+.ral-meta__row dt { width: 80px; color: var(--ral-muted); flex-shrink: 0; }
+.ral-meta__row dd { color: var(--ral-text); }
+
+.ral-entry-nav { display: flex; gap: 8px; align-items: center; }

data/app/assets/stylesheets/rails_audit_log/_08_pagination.css

@@ -0,0 +1,56 @@
+nav.pagy.series-nav {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-top: 16px;
+  font-size: 13px;
+}
+
+nav.pagy.series-nav a {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 32px;
+  height: 32px;
+  padding: 0 8px;
+  border: 1px solid var(--ral-border);
+  border-radius: 4px;
+  background: var(--ral-surface);
+  color: var(--ral-primary);
+  text-decoration: none;
+}
+
+nav.pagy.series-nav a:hover:not([aria-disabled="true"]) { background: var(--ral-bg); }
+
+nav.pagy.series-nav a[aria-current="page"] {
+  background: var(--ral-primary);
+  color: #fff;
+  border-color: var(--ral-primary);
+  font-weight: 600;
+}
+
+nav.pagy.series-nav a[aria-disabled="true"] {
+  color: #aaa;
+  cursor: default;
+  border-color: var(--ral-border-subtle);
+}
+
+nav.pagy.series-nav a[role="separator"] {
+  border: none;
+  color: var(--ral-muted);
+  min-width: auto;
+}
+
+.ral-pagination__link {
+  display: inline-flex;
+  align-items: center;
+  height: 32px;
+  padding: 0 10px;
+  border: 1px solid var(--ral-border);
+  border-radius: 4px;
+  background: var(--ral-surface);
+  color: var(--ral-primary);
+  text-decoration: none;
+  font-size: 13px;
+}
+.ral-pagination__link:hover { background: var(--ral-bg); text-decoration: none; }

data/app/assets/stylesheets/rails_audit_log/_09_filters.css

@@ -0,0 +1,54 @@
+.ral-filters {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  margin-bottom: 16px;
+}
+
+.ral-filter-input {
+  padding: 5px 10px;
+  font-size: 13px;
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  background: var(--ral-surface);
+  color: var(--ral-text);
+  min-width: 180px;
+}
+.ral-filter-input:focus { outline: 2px solid var(--ral-primary); outline-offset: -1px; }
+
+.ral-filter-select {
+  padding: 5px 8px;
+  font-size: 13px;
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  background: var(--ral-surface);
+  color: var(--ral-text);
+  cursor: pointer;
+}
+
+.ral-period-filter {
+  display: flex;
+  border: 1px solid var(--ral-border);
+  border-radius: var(--ral-radius);
+  overflow: hidden;
+  margin-left: auto;
+}
+
+.ral-period-btn {
+  padding: 5px 10px;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--ral-muted);
+  background: var(--ral-surface);
+  text-decoration: none;
+}
+.ral-period-btn + .ral-period-btn { border-left: 1px solid var(--ral-border); }
+.ral-period-btn:hover:not(.ral-period-btn--active) {
+  background: var(--ral-bg);
+  color: var(--ral-text);
+  text-decoration: none;
+}
+.ral-period-btn--active { background: var(--ral-primary); color: #fff; }
+
+.ral-filters__clear { font-size: 13px; }

data/app/assets/stylesheets/rails_audit_log/application.css

@@ -1,15 +1 @@
-/*
- * This is a manifest file that'll be compiled into application.css, which will include all the files
- * listed below.
- *
- * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
- * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
- *
- * You're free to add application-wide styles to this file and they'll appear at the bottom of the
- * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
- * files in this directory. Styles in this file should be added after the last require_* statement.
- * It is generally better to create a new file per style scope.
- *
- *= require_tree .
- *= require_self
- */
+/* Styles are loaded via the dashboard_stylesheets helper which globs _*.css files. */

data/app/concerns/rails_audit_log/auditable.rb

@@ -1,4 +1,24 @@
 module RailsAuditLog
+  # Include in any ActiveRecord model to automatically track +create+, +update+,
+  # and +destroy+ events as {AuditLogEntry} records.
+  #
+  # == Basic usage
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #   end
+  #
+  # == Configuring tracking
+  #
+  #   class Article < ApplicationRecord
+  #     include RailsAuditLog::Auditable
+  #     audit_log only: %i[title body],
+  #               meta: { tenant_id: -> { Current.tenant_id } },
+  #               version_limit: 50,
+  #               async: true
+  #   end
+  #
+  # Adds a polymorphic +has_many :audit_log_entries+ association to the model.
   module Auditable
     extend ActiveSupport::Concern
 
@@ -12,6 +32,8 @@ module RailsAuditLog
 
       _warn_if_audit_table_missing
 
+      # All {AuditLogEntry} records for this object, newest first by default.
+      # Destroyed when the object is destroyed.
       has_many :audit_log_entries,
                class_name: "RailsAuditLog::AuditLogEntry",
                as: :item,
@@ -54,6 +76,7 @@ module RailsAuditLog
     end
 
     class_methods do
+      # @api private
       def _warn_if_audit_table_missing
         return if connection.table_exists?("audit_log_entries")
 
@@ -66,6 +89,33 @@ module RailsAuditLog
         # DB not reachable during this phase (e.g. before db:create) — skip the check
       end
 
+      # Configures auditing options for this model. Call once in the class body
+      # after +include RailsAuditLog::Auditable+.
+      #
+      # @param only [Array<Symbol>, nil] whitelist of attributes to track;
+      #   when set, all other attributes are ignored regardless of +ignore:+
+      # @param ignore [Array<Symbol>, nil] additional attributes to exclude on
+      #   top of {RailsAuditLog.ignored_attributes}; ignored when +only:+ is set
+      # @param meta [Hash{Symbol => Proc}, nil] per-entry metadata; each value
+      #   is a lambda called at write time — zero-argument lambdas receive no
+      #   arguments, one-argument lambdas receive the record instance
+      # @param associations [Boolean, Array<Symbol>, nil] when +true+, tracks
+      #   all +has_many+ and +has_and_belongs_to_many+ associations; pass an
+      #   array of association names to track only specific ones
+      # @param version_limit [Integer, nil] maximum number of entries to retain
+      #   per record; oldest entries are pruned after each write; overrides
+      #   {RailsAuditLog.version_limit} for this model
+      # @param async [Boolean, nil] when +true+, writes are dispatched via
+      #   +WriteAuditLogJob+; overrides {RailsAuditLog.async} for this model
+      # @return [void]
+      # @example
+      #   class Article < ApplicationRecord
+      #     include RailsAuditLog::Auditable
+      #     audit_log only: %i[title body published_at],
+      #               meta: { tenant_id: -> { Current.tenant_id } },
+      #               associations: %i[tags],
+      #               version_limit: 100
+      #   end
       def audit_log(only: nil, ignore: nil, meta: nil, associations: nil, version_limit: nil, async: nil)
         self._audit_log_only          = only.map(&:to_s)   if only
         self._audit_log_ignore        = ignore.map(&:to_s) if ignore
@@ -76,6 +126,13 @@ module RailsAuditLog
       end
     end
 
+    # Executes the block with audit logging disabled for this record's writes.
+    # A convenience wrapper around {RailsAuditLog.disable}.
+    #
+    # @yield executes the block without recording any audit entries
+    # @return [Object] the return value of the block
+    # @example Skip auditing during a bulk update
+    #   post.skip_audit_log { post.update!(cached_at: Time.current) }
     def skip_audit_log
       RailsAuditLog.disable { yield }
     end

data/app/concerns/rails_audit_log/controller.rb

@@ -1,4 +1,21 @@
 module RailsAuditLog
+  # Include in +ApplicationController+ (or any controller) to automatically
+  # set and clear the current actor for every request, so that audit entries
+  # written during the request are tagged with the signed-in user.
+  #
+  # == Usage
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include RailsAuditLog::Controller
+  #     audit_log_actor { current_user }
+  #   end
+  #
+  # The block passed to {audit_log_actor} is evaluated in controller instance
+  # context on every request via a +before_action+. The actor is cleared in an
+  # +after_action+ so it never leaks between requests.
+  #
+  # Request metadata (+remote_ip+, +user_agent+) is captured automatically when
+  # {RailsAuditLog.capture_request_metadata} is +true+.
   module Controller
     extend ActiveSupport::Concern
 
@@ -10,10 +27,22 @@ module RailsAuditLog
     end
 
     class_methods do
+      # Registers a block that resolves the current actor for each request.
+      # The block is evaluated in controller instance context, so any helper
+      # method available to the controller (e.g. +current_user+) can be used.
+      #
+      # @yield block evaluated in controller context; should return the actor
+      # @return [void]
+      # @example
+      #   audit_log_actor { current_user }
+      #
+      #   # With a one-argument lambda style (actor = the controller instance)
+      #   audit_log_actor { |c| c.current_user }
       def audit_log_actor(&block)
         @audit_log_actor_block = block
       end
 
+      # @api private
       def audit_log_actor_block
         @audit_log_actor_block
       end

data/app/controllers/rails_audit_log/application_controller.rb

@@ -1,4 +1,17 @@
 module RailsAuditLog
+  # @api private
   class ApplicationController < ActionController::Base
+    include Pagy::Method
+
+    protect_from_forgery with: :exception
+    before_action :authenticate!
+
+    private
+
+    def authenticate!
+      return unless (auth = RailsAuditLog.authenticate)
+
+      instance_exec(self, &auth) || request_http_basic_authentication("Audit Log")
+    end
   end
 end

data/app/controllers/rails_audit_log/audit_log_entries_controller.rb

@@ -0,0 +1,32 @@
+module RailsAuditLog
+  # @api private
+  class AuditLogEntriesController < ApplicationController
+    def index
+      set_filters
+      @pagy, @entries = pagy(filtered_scope)
+      @item_types     = AuditLogEntry.distinct.order(:item_type).pluck(:item_type)
+    end
+
+    def show
+      @entry = AuditLogEntry.find(params[:id])
+    end
+
+    private
+
+    def set_filters
+      @event     = params[:event].presence_in(AuditLogEntry::EVENTS)
+      @item_type = params[:item_type].presence
+      @period    = params[:period].presence_in(AuditLogEntry::PERIODS.keys)
+      @q         = params[:q].presence
+    end
+
+    def filtered_scope
+      scope = AuditLogEntry.order(created_at: :desc)
+      scope = scope.where(event: @event)                          if @event
+      scope = scope.where(item_type: @item_type)                  if @item_type
+      scope = scope.for_period(@period)                           if @period
+      scope = scope.where("whodunnit_snapshot LIKE ?", "%#{@q}%") if @q
+      scope
+    end
+  end
+end

data/app/controllers/rails_audit_log/resources_controller.rb

@@ -0,0 +1,14 @@
+module RailsAuditLog
+  # @api private
+  class ResourcesController < ApplicationController
+    def show
+      @item_type = params[:item_type]
+      @item_id   = params[:item_id]
+      @pagy, @entries = pagy(
+        AuditLogEntry
+          .where(item_type: @item_type, item_id: @item_id)
+          .order(created_at: :asc)
+      )
+    end
+  end
+end

data/app/helpers/rails_audit_log/application_helper.rb

@@ -1,4 +1,18 @@
 module RailsAuditLog
+  # @api private
   module ApplicationHelper
+    def format_diff_value(value)
+      return "—" if value.nil?
+      return "#{value["type"]} ##{value["id"]}" if value.is_a?(Hash)
+
+      value.inspect
+    end
+
+    def dashboard_stylesheets
+      dir = RailsAuditLog::Engine.root.join("app/assets/stylesheets/rails_audit_log")
+      dir.glob("_*.css").sort.map do |file|
+        stylesheet_link_tag("rails_audit_log/#{file.basename}", media: "all")
+      end.join("\n").html_safe
+    end
   end
 end

data/app/javascript/rails_audit_log/application.js

@@ -0,0 +1,8 @@
+import "@hotwired/turbo"
+import { Application } from "@hotwired/stimulus"
+import SearchController from "rails_audit_log/search_controller"
+import DiffController   from "rails_audit_log/diff_controller"
+
+const application = Application.start()
+application.register("search", SearchController)
+application.register("diff",   DiffController)

data/app/javascript/rails_audit_log/diff_controller.js

@@ -0,0 +1,20 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class DiffController extends Controller {
+  static targets = ["inline", "side", "inlineBtn", "sideBtn"]
+
+  connect() {
+    this.setMode(localStorage.getItem("ral-diff-mode") || "inline")
+  }
+
+  setInline() { this.setMode("inline") }
+  setSide()   { this.setMode("side") }
+
+  setMode(mode) {
+    localStorage.setItem("ral-diff-mode", mode)
+    this.inlineTarget.hidden = mode !== "inline"
+    this.sideTarget.hidden   = mode !== "side"
+    this.inlineBtnTarget.classList.toggle("ral-diff-btn--active", mode === "inline")
+    this.sideBtnTarget.classList.toggle("ral-diff-btn--active", mode === "side")
+  }
+}

data/app/javascript/rails_audit_log/search_controller.js

@@ -0,0 +1,12 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class SearchController extends Controller {
+  filter() {
+    clearTimeout(this._timeout)
+    this._timeout = setTimeout(() => this.element.requestSubmit(), 300)
+  }
+
+  select() {
+    this.element.requestSubmit()
+  }
+}

data/app/jobs/rails_audit_log/application_job.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ApplicationJob < ActiveJob::Base
   end
 end

data/app/models/rails_audit_log/application_record.rb

@@ -1,4 +1,5 @@
 module RailsAuditLog
+  # @api private
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
   end