trakable 0.2.0

data/integration/scenarios/38-concurrency/scenario.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# Scenario 38: Concurrency
+# Tests thread-safety of Context, Tracker, and trak creation under concurrent load
+
+require_relative '../scenario_runner'
+
+run_scenario 'Concurrency' do
+  puts '=== TEST 1: Context isolation between threads ==='
+
+  results = {}
+  threads = 10.times.map do |i|
+    Thread.new do
+      user = "User_#{i}"
+      Trakable::Context.with_user(user) do
+        sleep(rand * 0.01) # Random delay to provoke interleaving
+        results[i] = Trakable::Context.whodunnit
+      end
+    end
+  end
+
+  threads.each(&:join)
+
+  10.times do |i|
+    assert_equal "User_#{i}", results[i], "Thread #{i} saw wrong whodunnit: #{results[i]}"
+  end
+  puts '   ✓ Each thread sees its own whodunnit'
+
+  puts '=== TEST 2: Context reset does not leak between threads ==='
+
+  leak_detected = false
+  barrier = Queue.new
+
+  t1 = Thread.new do
+    Trakable::Context.with_user('ThreadA') do
+      barrier << :ready
+      sleep 0.02
+      leak_detected = true if Trakable::Context.whodunnit != 'ThreadA'
+    end
+  end
+
+  t2 = Thread.new do
+    barrier.pop # Wait for t1 to set context
+    Trakable::Context.with_user('ThreadB') do
+      sleep 0.01
+    end
+  end
+
+  [t1, t2].each(&:join)
+  refute leak_detected, 'Thread A context was corrupted by Thread B'
+  puts '   ✓ Concurrent contexts do not leak'
+
+  puts '=== TEST 3: without_tracking is thread-local ==='
+
+  tracking_states = {}
+
+  threads = 5.times.map do |i|
+    Thread.new do
+      if i.even?
+        Trakable::Context.without_tracking do
+          sleep(rand * 0.01)
+          tracking_states[i] = Trakable::Context.tracking_enabled?
+        end
+      else
+        sleep(rand * 0.01)
+        tracking_states[i] = Trakable::Context.tracking_enabled?
+      end
+    end
+  end
+
+  threads.each(&:join)
+
+  5.times do |i|
+    if i.even?
+      assert_equal false, tracking_states[i], "Thread #{i} should have tracking disabled"
+    else
+      assert_equal true, tracking_states[i], "Thread #{i} should have tracking enabled"
+    end
+  end
+  puts '   ✓ without_tracking is thread-local'
+
+  puts '=== TEST 4: Concurrent Tracker.call produces independent traks ==='
+
+  records = 20.times.map do |i|
+    record = Object.new
+    record.define_singleton_method(:id) { i }
+    record.define_singleton_method(:class) { Struct.new(:name).new("Post") }
+    record.define_singleton_method(:previous_changes) { { 'title' => ["Old_#{i}", "New_#{i}"] } }
+    record.define_singleton_method(:attributes) { { 'id' => i, 'title' => "New_#{i}" } }
+    record
+  end
+
+  traks = []
+  mutex = Mutex.new
+
+  threads = records.map do |record|
+    Thread.new do
+      trak = Trakable::Tracker.call(record, 'update')
+      mutex.synchronize { traks << trak }
+    end
+  end
+
+  threads.each(&:join)
+
+  assert_equal 20, traks.length, "Expected 20 traks, got #{traks.length}"
+
+  item_ids = traks.map(&:item_id).sort
+  assert_equal (0..19).to_a, item_ids, 'Each record should have exactly one trak'
+  puts '   ✓ 20 concurrent Tracker.call produce 20 independent traks'
+
+  puts '=== TEST 5: Concurrent whodunnit assignment per thread ==='
+
+  traks = []
+  mutex = Mutex.new
+
+  threads = 10.times.map do |i|
+    Thread.new do
+      actor = Struct.new(:id, :class).new(i, Struct.new(:name).new("Actor"))
+      Trakable::Context.with_user(actor) do
+        record = Object.new
+        record.define_singleton_method(:id) { i }
+        record.define_singleton_method(:class) { Struct.new(:name).new("Post") }
+        record.define_singleton_method(:previous_changes) { { 'title' => ['a', 'b'] } }
+        record.define_singleton_method(:attributes) { { 'id' => i, 'title' => 'b' } }
+
+        trak = Trakable::Tracker.call(record, 'update')
+        mutex.synchronize { traks << trak }
+      end
+    end
+  end
+
+  threads.each(&:join)
+
+  traks.each do |trak|
+    assert_equal trak.item_id, trak.whodunnit_id,
+                 "Trak for item #{trak.item_id} has whodunnit #{trak.whodunnit_id}"
+  end
+  puts '   ✓ Each thread whodunnit is correctly paired with its trak'
+
+  puts '=== TEST 6: Stress test — 100 threads ==='
+
+  traks = []
+  mutex = Mutex.new
+
+  threads = 100.times.map do |i|
+    Thread.new do
+      record = Object.new
+      record.define_singleton_method(:id) { i }
+      record.define_singleton_method(:class) { Struct.new(:name).new("StressModel") }
+      record.define_singleton_method(:previous_changes) { {} }
+      record.define_singleton_method(:attributes) { { 'id' => i } }
+
+      trak = Trakable::Tracker.call(record, 'create')
+      mutex.synchronize { traks << trak }
+    end
+  end
+
+  threads.each(&:join)
+
+  assert_equal 100, traks.length
+  assert_equal 100, traks.map(&:item_id).uniq.length, 'All 100 traks should be unique'
+  puts '   ✓ 100 concurrent threads produce 100 unique traks'
+end

data/integration/scenarios/39-query-scopes/scenario.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Scenario 39: Query Scopes
+# Tests the AR-only scopes defined on Trakable::Trak
+# Since integration tests run without AR, we verify the non-AR path
+# and simulate the scope logic to validate correctness.
+
+require_relative '../scenario_runner'
+
+run_scenario 'Query Scopes' do
+  puts '=== TEST 1: Scopes are not defined in non-AR mode ==='
+
+  refute Trakable::Trak.respond_to?(:for_item_type), 'for_item_type should not exist without AR'
+  refute Trakable::Trak.respond_to?(:for_event), 'for_event should not exist without AR'
+  refute Trakable::Trak.respond_to?(:for_whodunnit), 'for_whodunnit should not exist without AR'
+  refute Trakable::Trak.respond_to?(:created_before), 'created_before should not exist without AR'
+  refute Trakable::Trak.respond_to?(:created_after), 'created_after should not exist without AR'
+  refute Trakable::Trak.respond_to?(:recent), 'recent should not exist without AR'
+  puts '   ✓ Scopes are AR-only (not defined in plain Ruby mode)'
+
+  puts '=== TEST 2: Scope logic — for_item_type ==='
+
+  traks = [
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create'),
+    Trakable::Trak.new(item_type: 'Post', item_id: 2, event: 'update'),
+    Trakable::Trak.new(item_type: 'Comment', item_id: 1, event: 'create'),
+    Trakable::Trak.new(item_type: 'User', item_id: 1, event: 'destroy')
+  ]
+
+  post_traks = traks.select { |t| t.item_type == 'Post' }
+  assert_equal 2, post_traks.length
+  puts '   ✓ for_item_type filters by item_type'
+
+  puts '=== TEST 3: Scope logic — for_event ==='
+
+  creates = traks.select { |t| t.event == 'create' }
+  assert_equal 2, creates.length
+
+  updates = traks.select { |t| t.event == 'update' }
+  assert_equal 1, updates.length
+
+  destroys = traks.select { |t| t.event == 'destroy' }
+  assert_equal 1, destroys.length
+  puts '   ✓ for_event filters by event type'
+
+  puts '=== TEST 4: Scope logic — for_whodunnit (polymorphic) ==='
+
+  traks_with_actors = [
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create',
+                       whodunnit_type: 'User', whodunnit_id: 1),
+    Trakable::Trak.new(item_type: 'Post', item_id: 2, event: 'update',
+                       whodunnit_type: 'User', whodunnit_id: 2),
+    Trakable::Trak.new(item_type: 'Post', item_id: 3, event: 'create',
+                       whodunnit_type: 'Admin', whodunnit_id: 1),
+    Trakable::Trak.new(item_type: 'Post', item_id: 4, event: 'destroy',
+                       whodunnit_type: nil, whodunnit_id: nil)
+  ]
+
+  user1_traks = traks_with_actors.select { |t| t.whodunnit_type == 'User' && t.whodunnit_id == 1 }
+  assert_equal 1, user1_traks.length
+
+  admin_traks = traks_with_actors.select { |t| t.whodunnit_type == 'Admin' }
+  assert_equal 1, admin_traks.length
+
+  anonymous_traks = traks_with_actors.select { |t| t.whodunnit_type.nil? }
+  assert_equal 1, anonymous_traks.length
+  puts '   ✓ for_whodunnit filters by type + id (polymorphic)'
+
+  puts '=== TEST 5: Scope logic — created_before / created_after ==='
+
+  now = Time.now
+  traks_timed = [
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create', created_at: now - 7200),
+    Trakable::Trak.new(item_type: 'Post', item_id: 2, event: 'update', created_at: now - 3600),
+    Trakable::Trak.new(item_type: 'Post', item_id: 3, event: 'update', created_at: now - 1800),
+    Trakable::Trak.new(item_type: 'Post', item_id: 4, event: 'destroy', created_at: now)
+  ]
+
+  cutoff = now - 3600
+
+  before = traks_timed.select { |t| t.created_at < cutoff }
+  assert_equal 1, before.length
+  assert_equal 1, before.first.item_id
+
+  after = traks_timed.select { |t| t.created_at > cutoff }
+  assert_equal 2, after.length
+  puts '   ✓ created_before / created_after filter by timestamp'
+
+  puts '=== TEST 6: Scope logic — recent (order desc) ==='
+
+  sorted = traks_timed.sort_by { |t| -t.created_at.to_f }
+  assert_equal 4, sorted.first.item_id
+  assert_equal 1, sorted.last.item_id
+  puts '   ✓ recent orders by created_at desc'
+
+  puts '=== TEST 7: Scope chaining simulation ==='
+
+  all_traks = [
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create', created_at: now - 7200,
+                       whodunnit_type: 'User', whodunnit_id: 1),
+    Trakable::Trak.new(item_type: 'Post', item_id: 2, event: 'update', created_at: now - 3600,
+                       whodunnit_type: 'User', whodunnit_id: 1),
+    Trakable::Trak.new(item_type: 'Comment', item_id: 1, event: 'update', created_at: now - 1800,
+                       whodunnit_type: 'User', whodunnit_id: 1),
+    Trakable::Trak.new(item_type: 'Post', item_id: 3, event: 'update', created_at: now,
+                       whodunnit_type: 'Admin', whodunnit_id: 2)
+  ]
+
+  # Simulate: for_item_type('Post').for_event(:update).created_after(1.day.ago).recent
+  result = all_traks
+           .select { |t| t.item_type == 'Post' }
+           .select { |t| t.event == 'update' }
+           .select { |t| t.created_at > now - 86_400 }
+           .sort_by { |t| -t.created_at.to_f }
+
+  assert_equal 2, result.length
+  assert_equal 3, result.first.item_id, 'Most recent should be first'
+  assert_equal 2, result.last.item_id
+  puts '   ✓ Chained scopes filter and sort correctly'
+
+  puts '=== TEST 8: Edge case — empty result ==='
+
+  empty = all_traks.select { |t| t.item_type == 'NonExistent' }
+  assert_equal 0, empty.length
+  puts '   ✓ Scopes return empty array when nothing matches'
+end

data/integration/scenarios/40-whodunnit-config/scenario.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Scenario 40: Whodunnit Config
+# Tests config.whodunnit_method global configuration
+
+require_relative '../scenario_runner'
+
+run_scenario 'Whodunnit Config' do
+  puts '=== TEST 1: Default whodunnit_method is :current_user ==='
+
+  assert_equal :current_user, Trakable.configuration.whodunnit_method
+  puts '   ✓ Default is :current_user'
+
+  puts '=== TEST 2: whodunnit_method is configurable ==='
+
+  Trakable.configure do |config|
+    config.whodunnit_method = :current_admin
+  end
+
+  assert_equal :current_admin, Trakable.configuration.whodunnit_method
+  puts '   ✓ Changed to :current_admin'
+
+  puts '=== TEST 3: Controller reads from global config ==='
+
+  # Simulate a controller that uses the configured method
+  controller_class = Class.new do
+    attr_accessor :current_admin
+
+    def whodunnit_method
+      Trakable.configuration.whodunnit_method
+    end
+
+    def perform_action(&block)
+      user = send(whodunnit_method)
+      Trakable.with_user(user, &block)
+    end
+  end
+
+  admin = Struct.new(:id, :class).new(42, Struct.new(:name).new('Admin'))
+  controller = controller_class.new
+  controller.current_admin = admin
+
+  controller.perform_action do
+    assert_equal admin, Trakable::Context.whodunnit
+  end
+  puts '   ✓ Controller uses configured method'
+
+  puts '=== TEST 4: Tracker picks up whodunnit from context ==='
+
+  actor = Struct.new(:id, :class).new(99, Struct.new(:name).new('Admin'))
+
+  Trakable::Context.with_user(actor) do
+    record = Object.new
+    record.define_singleton_method(:id) { 1 }
+    record.define_singleton_method(:class) { Struct.new(:name).new('Post') }
+    record.define_singleton_method(:previous_changes) { { 'title' => %w[Old New] } }
+    record.define_singleton_method(:attributes) { { 'id' => 1, 'title' => 'New' } }
+
+    trak = Trakable::Tracker.call(record, 'update')
+
+    assert_equal 'Admin', trak.whodunnit_type
+    assert_equal 99, trak.whodunnit_id
+  end
+  puts '   ✓ Tracker records whodunnit from context'
+
+  puts '=== TEST 5: Different whodunnit types (polymorphic) ==='
+
+  actor_types = [
+    Struct.new(:id, :class).new(1, Struct.new(:name).new('User')),
+    Struct.new(:id, :class).new(2, Struct.new(:name).new('Admin')),
+    Struct.new(:id, :class).new(3, Struct.new(:name).new('ApiKey')),
+    Struct.new(:id, :class).new(4, Struct.new(:name).new('ServiceAccount'))
+  ]
+
+  traks = actor_types.map do |actor|
+    Trakable::Context.with_user(actor) do
+      record = Object.new
+      record.define_singleton_method(:id) { actor.id }
+      record.define_singleton_method(:class) { Struct.new(:name).new('Post') }
+      record.define_singleton_method(:previous_changes) { { 'x' => [0, 1] } }
+      record.define_singleton_method(:attributes) { { 'id' => actor.id } }
+
+      Trakable::Tracker.call(record, 'update')
+    end
+  end
+
+  types = traks.map(&:whodunnit_type)
+  assert_equal %w[User Admin ApiKey ServiceAccount], types
+  puts '   ✓ Works with User, Admin, ApiKey, ServiceAccount'
+
+  puts '=== TEST 6: Nil whodunnit (anonymous/system changes) ==='
+
+  record = Object.new
+  record.define_singleton_method(:id) { 1 }
+  record.define_singleton_method(:class) { Struct.new(:name).new('Post') }
+  record.define_singleton_method(:previous_changes) { { 'status' => [0, 1] } }
+  record.define_singleton_method(:attributes) { { 'id' => 1 } }
+
+  trak = Trakable::Tracker.call(record, 'update')
+
+  assert_nil trak.whodunnit_type
+  assert_nil trak.whodunnit_id
+  puts '   ✓ Anonymous changes have nil whodunnit'
+
+  puts '=== TEST 7: Reset config ==='
+
+  Trakable.configure do |config|
+    config.whodunnit_method = :current_user
+  end
+
+  assert_equal :current_user, Trakable.configuration.whodunnit_method
+  puts '   ✓ Config reset to default'
+end

data/integration/scenarios/41-batch-cleanup/scenario.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# Scenario 41: Batch Cleanup
+# Tests Cleanup.run_retention with batch deletion and Cleanup.run per-record
+
+require_relative '../scenario_runner'
+
+# Mock AR-like relation that supports limit + delete_all for batch testing
+class BatchMockRelation
+  attr_reader :deleted_count, :delete_calls
+
+  def initialize(total_rows)
+    @remaining = total_rows
+    @deleted_count = 0
+    @delete_calls = 0
+  end
+
+  def where(*)
+    self
+  end
+
+  def limit(n)
+    @current_limit = n
+    self
+  end
+
+  def delete_all
+    @delete_calls += 1
+    to_delete = [@remaining, @current_limit || @remaining].min
+    @remaining -= to_delete
+    @deleted_count += to_delete
+    to_delete
+  end
+
+  def respond_to?(method, *)
+    %i[where limit delete_all].include?(method) || super
+  end
+end
+
+# Mock Trak class that returns our mock relation
+class BatchMockTrak
+  class << self
+    attr_accessor :relation
+
+    def where(*)
+      relation
+    end
+
+    def respond_to?(method, *)
+      %i[where].include?(method) || super
+    end
+
+    def arel_table
+      @arel_table ||= Struct.new(:nothing).new.tap do |at|
+        at.define_singleton_method(:[]) { |_col| Struct.new(:lt).new(proc { |_t| true }) }
+      end
+    end
+  end
+end
+
+# Mock record with traks for per-record cleanup
+class BatchCleanupRecord
+  attr_reader :trakable_options, :traks_data
+
+  def initialize(max_traks:, trak_count:)
+    @trakable_options = { max_traks: max_traks }
+    @traks_data = trak_count.times.map { |i| { id: i, created_at: Time.now - (trak_count - i) } }
+  end
+
+  def traks
+    BatchRecordRelation.new(self)
+  end
+end
+
+class BatchRecordRelation
+  def initialize(record)
+    @record = record
+  end
+
+  def respond_to?(method, *)
+    %i[where order offset delete_all].include?(method) || super
+  end
+
+  def order(*)
+    @sorted = @record.traks_data.sort_by { |t| -t[:created_at].to_f }
+    self
+  end
+
+  def offset(n)
+    @sorted = (@sorted || @record.traks_data).drop(n)
+    self
+  end
+
+  def delete_all
+    ids_to_delete = @sorted.map { |t| t[:id] }
+    @record.traks_data.reject! { |t| ids_to_delete.include?(t[:id]) }
+    ids_to_delete.length
+  end
+end
+
+run_scenario 'Batch Cleanup' do
+  puts '=== TEST 1: run_retention returns nil without retention config ==='
+
+  model_class = Class.new do
+    def self.trakable_options
+      {}
+    end
+  end
+
+  result = Trakable::Cleanup.run_retention(model_class)
+  assert_nil result
+  puts '   ✓ Returns nil when no retention configured'
+
+  puts '=== TEST 2: run_retention returns 0 when no old traks ==='
+
+  model_with_retention = Class.new do
+    def self.trakable_options
+      { retention: 90 * 86_400 }
+    end
+
+    def self.to_s
+      'CleanModel'
+    end
+  end
+
+  result = Trakable::Cleanup.run_retention(model_with_retention)
+  assert_equal 0, result
+  puts '   ✓ Returns 0 when nothing to delete'
+
+  puts '=== TEST 3: run_retention accepts custom batch_size ==='
+
+  result = Trakable::Cleanup.run_retention(model_with_retention, batch_size: 500)
+  assert_equal 0, result
+  puts '   ✓ batch_size parameter accepted'
+
+  puts '=== TEST 4: run_retention accepts override retention_period ==='
+
+  model_no_retention = Class.new do
+    def self.trakable_options
+      {}
+    end
+
+    def self.to_s
+      'NoRetentionModel'
+    end
+  end
+
+  result = Trakable::Cleanup.run_retention(model_no_retention, retention_period: 30 * 86_400)
+  # Should run (not nil) because we override
+  assert_equal 0, result
+  puts '   ✓ retention_period override works'
+
+  puts '=== TEST 5: BATCH_SIZE constant is defined ==='
+
+  assert_equal 1_000, Trakable::Cleanup::BATCH_SIZE
+  puts '   ✓ Default BATCH_SIZE is 1,000'
+
+  puts '=== TEST 6: Per-record cleanup enforces max_traks ==='
+
+  record = BatchCleanupRecord.new(max_traks: 3, trak_count: 10)
+  assert_equal 10, record.traks_data.length
+
+  Trakable::Cleanup.run(record)
+
+  assert_equal 3, record.traks_data.length, "Expected 3 traks, got #{record.traks_data.length}"
+  # Should keep the 3 most recent (highest IDs)
+  kept_ids = record.traks_data.map { |t| t[:id] }.sort
+  assert_equal [7, 8, 9], kept_ids
+  puts '   ✓ max_traks keeps only the N most recent'
+
+  puts '=== TEST 7: Per-record cleanup is a no-op when under limit ==='
+
+  record = BatchCleanupRecord.new(max_traks: 10, trak_count: 3)
+  Trakable::Cleanup.run(record)
+
+  assert_equal 3, record.traks_data.length
+  puts '   ✓ No deletion when trak count is under max_traks'
+
+  puts '=== TEST 8: Cleanup.run returns true ==='
+
+  record = BatchCleanupRecord.new(max_traks: 5, trak_count: 5)
+  result = Trakable::Cleanup.run(record)
+
+  assert_equal true, result
+  puts '   ✓ Cleanup.run always returns true'
+end

data/integration/scenarios/scenario_runner.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../../test/test_helper'
+require 'securerandom'
+require 'active_support/core_ext/integer/time'
+require 'active_support/core_ext/numeric/time'
+
+# Scenario runner helper
+# Include this in your scenario files
+
+def run_scenario(name)
+  puts "\n#{'=' * 60}"
+  puts "SCENARIO: #{name}"
+  puts '=' * 60
+  yield
+  puts "\n#{'=' * 60}"
+  puts "SCENARIO #{name} COMPLETE"
+  puts '=' * 60
+rescue StandardError => e
+  puts "\n#{'!' * 60}"
+  puts "SCENARIO FAILED: #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+  puts '!' * 60
+  raise e
+end
+
+def assert(condition, message = 'Assertion failed')
+  raise message unless condition
+end
+
+def assert_equal(expected, actual, message = nil)
+  msg = message || "Expected #{expected.inspect}, got #{actual.inspect}"
+  raise msg unless expected == actual
+end
+
+def assert_kind_of(klass, obj)
+  raise "Expected #{klass}, got #{obj.class}" unless obj.is_a?(klass)
+end
+
+def assert_includes(collection, item)
+  raise "Expected #{collection.inspect} to include #{item.inspect}" unless collection.include?(item)
+end
+
+def assert_nil(obj)
+  raise "Expected nil, got #{obj.inspect}" unless obj.nil?
+end
+
+def refute(condition, message = 'Expected condition to be false')
+  raise message if condition
+end
+
+def refute_nil(obj, message = 'Expected non-nil value')
+  raise message if obj.nil?
+end
+
+def refute_equal(expected, actual)
+  raise "Expected #{actual.inspect} to not equal #{expected.inspect}" if expected == actual
+end
+
+# Refute helper (alias for refute)
+def refute(condition, message = 'Expected condition to be false')
+  raise message if condition
+end
+
+# Assert with message
+def assert_with_message(condition, message = 'Assertion failed')
+  raise message unless condition
+end

data/lib/generators/trakable/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Trakable
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a migration and initializer for Trakable.'
+
+      def self.next_migration_number(_dir)
+        Time.now.utc.strftime('%Y%m%d%H%M%S')
+      end
+
+      def copy_migration
+        migration_template 'create_traks_migration.rb', 'db/migrate/create_traks.rb'
+      end
+
+      def copy_initializer
+        template 'trakable_initializer.rb', 'config/initializers/trakable.rb'
+      end
+    end
+  end
+end