trakable 0.2.0

data/benchmark/full_benchmark.rb

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Unified Benchmark for Trakable
+# Measures 5 dimensions in one run: Boot, Speed, Memory, Storage, Integration
+#
+# Usage:
+#   ruby benchmark/full_benchmark.rb
+#   ruby benchmark/full_benchmark.rb > /tmp/before.txt
+#   # ... apply changes ...
+#   ruby benchmark/full_benchmark.rb > /tmp/after.txt
+#   diff /tmp/before.txt /tmp/after.txt
+
+ENV['DISABLE_COVERAGE'] = '1'
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'benchmark'
+require 'json'
+require 'trakable'
+
+SPEED_ITERATIONS = 50_000
+SPEED_RUNS = 5
+ALLOC_ITERATIONS = 10_000
+
+results = {}
+
+# ---------------------------------------------------------------------------
+# A. Boot — subprocess `ruby -e "require 'trakable'"` × 5, median
+# ---------------------------------------------------------------------------
+boot_times = 5.times.map do
+  cmd = %(ruby -I#{File.expand_path('../lib', __dir__)} -e "require 'trakable'")
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  system(cmd, out: File::NULL, err: File::NULL)
+  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  ((t1 - t0) * 1_000_000).round(0)
+end.sort
+results['boot_time_us'] = boot_times[2] # median
+
+# ---------------------------------------------------------------------------
+# Mocks
+# ---------------------------------------------------------------------------
+class BenchRecord
+  attr_accessor :trakable_options, :previous_changes
+
+  def initialize
+    @trakable_options = { only: %w[title body], ignore: %w[status] }
+    @previous_changes = {
+      'title' => %w[OldTitle NewTitle],
+      'body'  => %w[OldBody NewBody],
+      'views' => [0, 10],
+      'updated_at' => [Time.now - 3600, Time.now],
+      'status' => %w[draft published]
+    }
+  end
+
+  def id = 1
+  def self.name = 'BenchRecord'
+
+  def attributes
+    { 'id' => 1, 'title' => 'NewTitle', 'body' => 'NewBody',
+      'views' => 10, 'status' => 'published' }
+  end
+end
+
+class WideRecord
+  attr_accessor :trakable_options, :previous_changes
+
+  def initialize
+    @trakable_options = {}
+    @previous_changes = {
+      'field_03' => %w[old new],
+      'field_07' => %w[old new]
+    }
+  end
+
+  def id = 2
+  def self.name = 'WideRecord'
+
+  def attributes
+    h = { 'id' => 2 }
+    20.times { |i| h["field_#{format('%02d', i)}"] = "value_#{i}" }
+    h
+  end
+end
+
+# ---------------------------------------------------------------------------
+# B. Speed — Benchmark.realtime × SPEED_ITERATIONS × SPEED_RUNS, median
+# ---------------------------------------------------------------------------
+def median_speed(record, event)
+  # warmup
+  100.times { Trakable::Tracker.call(record, event) }
+
+  runs = SPEED_RUNS.times.map do
+    t = Benchmark.realtime { SPEED_ITERATIONS.times { Trakable::Tracker.call(record, event) } }
+    (t / SPEED_ITERATIONS * 1_000_000).round(2)
+  end.sort
+  runs[2]
+end
+
+bench = BenchRecord.new
+results['speed_create_us'] = median_speed(bench, 'create')
+results['speed_update_us'] = median_speed(bench, 'update')
+results['speed_destroy_us'] = median_speed(bench, 'destroy')
+
+# ---------------------------------------------------------------------------
+# C. Memory — GC.stat[:total_allocated_objects] × ALLOC_ITERATIONS
+# ---------------------------------------------------------------------------
+def measure_allocs(record, event)
+  # warmup
+  100.times { Trakable::Tracker.call(record, event) }
+
+  GC.start
+  GC.disable
+  before = GC.stat[:total_allocated_objects]
+  ALLOC_ITERATIONS.times { Trakable::Tracker.call(record, event) }
+  after = GC.stat[:total_allocated_objects]
+  GC.enable
+  ((after - before).to_f / ALLOC_ITERATIONS).round(1)
+end
+
+def measure_allocs_breakdown(record, event)
+  100.times { Trakable::Tracker.call(record, event) }
+
+  GC.start
+  GC.disable
+  before = ObjectSpace.count_objects.dup
+  ALLOC_ITERATIONS.times { Trakable::Tracker.call(record, event) }
+  after = ObjectSpace.count_objects
+  GC.enable
+
+  result = {}
+  after.each do |type, count|
+    diff = count - (before[type] || 0)
+    result[type] = (diff.to_f / ALLOC_ITERATIONS).round(1) if diff > 0
+  end
+  result
+end
+
+bench = BenchRecord.new
+results['allocs_create'] = measure_allocs(bench, 'create')
+results['allocs_update'] = measure_allocs(bench, 'update')
+results['allocs_destroy'] = measure_allocs(bench, 'destroy')
+
+breakdown = measure_allocs_breakdown(bench, 'update')
+breakdown.each do |type, val|
+  results["allocs_update_#{type}"] = val
+end
+
+# ---------------------------------------------------------------------------
+# D. Storage — JSON.generate(trak.object).bytesize
+# ---------------------------------------------------------------------------
+def storage_metrics(record, event, prefix)
+  trak = Trakable::Tracker.call(record, event)
+  result = {}
+  obj = trak.object
+  cs  = trak.changeset
+
+  result["#{prefix}object_bytes"]    = obj ? JSON.generate(obj).bytesize : 0
+  result["#{prefix}changeset_bytes"] = cs && !cs.empty? ? JSON.generate(cs).bytesize : 0
+  result["#{prefix}total_bytes"]     = result["#{prefix}object_bytes"] + result["#{prefix}changeset_bytes"]
+  result
+end
+
+bench = BenchRecord.new
+results.merge!(storage_metrics(bench, 'update', 'storage_'))
+results.merge!(storage_metrics(bench, 'destroy', 'storage_destroy_'))
+
+wide = WideRecord.new
+results.merge!(storage_metrics(wide, 'update', 'storage_wide_'))
+
+# ---------------------------------------------------------------------------
+# E. Integration — Load scenarios with GC counting
+# ---------------------------------------------------------------------------
+scenarios_dir = File.expand_path('../integration/scenarios', __dir__)
+if Dir.exist?(scenarios_dir)
+  scenario_dirs = Dir.glob("#{scenarios_dir}/*").select { |d| File.directory?(d) }.sort
+  total_allocs = 0
+  scenario_count = 0
+
+  real_stdout = $stdout
+
+  scenario_dirs.each do |dir|
+    scenario_file = File.join(dir, 'scenario.rb')
+    next unless File.exist?(scenario_file)
+
+    Trakable::Context.reset!
+    $stdout = File.open(File::NULL, 'w')
+
+    GC.start
+    GC.disable
+    before = GC.stat[:total_allocated_objects]
+
+    begin
+      load scenario_file
+    rescue StandardError
+      # skip failures
+    end
+
+    after = GC.stat[:total_allocated_objects]
+    GC.enable
+
+    $stdout.close
+    $stdout = real_stdout
+
+    total_allocs += (after - before)
+    scenario_count += 1
+  end
+
+  $stdout = real_stdout
+  results['integration_scenarios'] = scenario_count
+  results['integration_total_allocs'] = total_allocs
+end
+
+# ---------------------------------------------------------------------------
+# Output — sorted table, diffable
+# ---------------------------------------------------------------------------
+puts format('%-40s | %s', 'metric', 'value')
+puts '-' * 60
+results.sort_by { |k, _| k }.each do |key, value|
+  puts format('%-40s | %s', key, value)
+end

data/benchmark/integration_memory.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Integration Memory Benchmark for Trakable
+# Measures allocations across all integration scenarios
+#
+# Usage:
+#   ruby benchmark/integration_memory.rb
+
+ENV['DISABLE_COVERAGE'] = '1'
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'trakable'
+
+scenarios_dir = File.expand_path('../integration/scenarios', __dir__)
+scenario_dirs = Dir.glob("#{scenarios_dir}/*").select { |d| File.directory?(d) }.sort
+
+results = []
+real_stdout = $stdout
+
+scenario_dirs.each do |dir|
+  scenario_file = File.join(dir, 'scenario.rb')
+  next unless File.exist?(scenario_file)
+
+  name = File.basename(dir)
+  Trakable::Context.reset!
+
+  # Suppress output
+  $stdout = File.open(File::NULL, 'w')
+
+  GC.start
+  GC.disable
+  before = GC.stat[:total_allocated_objects]
+
+  begin
+    load scenario_file
+    status = 'PASS'
+  rescue StandardError => e
+    status = "FAIL"
+  end
+
+  after = GC.stat[:total_allocated_objects]
+  GC.enable
+
+  $stdout.close
+  $stdout = real_stdout
+
+  results << { name: name, allocs: after - before, status: status }
+end
+
+$stdout = real_stdout
+
+puts '=' * 70
+puts 'Trakable Integration Memory Benchmark'
+puts '=' * 70
+puts
+
+total = 0
+results.each do |r|
+  total += r[:allocs]
+  flag = r[:status] == 'PASS' ? ' ' : 'F'
+  printf "[%s] %-45s %7d allocs\n", flag, r[:name][0..44], r[:allocs]
+end
+
+puts '-' * 70
+printf "    %-45s %7d allocs\n", "TOTAL (#{results.size} scenarios)", total
+puts
+
+gc = GC.stat
+puts "GC runs: #{gc[:count]} | Live objects: #{gc[:heap_live_slots]}"
+puts '=' * 70

data/benchmark/memory_benchmark.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Memory & Allocation Benchmark for Trakable
+# Measures object allocations and GC pressure for common operations
+#
+# Usage:
+#   ruby benchmark/memory_benchmark.rb
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'trakable'
+
+puts '=' * 60
+puts 'Trakable Memory & Allocation Benchmark'
+puts '=' * 60
+puts
+
+ITERATIONS = 10_000
+
+# --- Helpers ---
+
+def measure_allocs(n = ITERATIONS)
+  GC.start
+  GC.disable
+  before = GC.stat[:total_allocated_objects]
+  n.times { yield }
+  after = GC.stat[:total_allocated_objects]
+  GC.enable
+  (after - before).to_f / n
+end
+
+def measure_allocs_by_type(n = ITERATIONS)
+  GC.start
+  GC.disable
+  before = ObjectSpace.count_objects.dup
+  n.times { yield }
+  after = ObjectSpace.count_objects
+  GC.enable
+  result = {}
+  after.each do |type, count|
+    diff = count - (before[type] || 0)
+    result[type] = (diff.to_f / n).round(1) if diff > 0
+  end
+  result
+end
+
+def measure_memory_bytes(n = ITERATIONS)
+  GC.start
+  before = GC.stat[:malloc_increase_bytes]
+  n.times { yield }
+  after = GC.stat[:malloc_increase_bytes]
+  ((after - before).to_f / n).round(1)
+end
+
+# --- Mock ---
+
+class MockRecord
+  attr_accessor :trakable_options, :previous_changes
+
+  def initialize
+    @trakable_options = { only: %w[title body], ignore: %w[status] }
+    @previous_changes = {
+      'title' => %w[Old New], 'body' => %w[Old New],
+      'views' => [0, 10], 'updated_at' => [Time.now - 3600, Time.now],
+      'status' => %w[draft published]
+    }
+  end
+
+  def id
+    1
+  end
+
+  def attributes
+    { 'id' => 1, 'title' => 'New', 'body' => 'New', 'views' => 10, 'status' => 'published' }
+  end
+end
+
+# --- Tests ---
+
+record = MockRecord.new
+
+# Warmup
+5.times { Trakable::Tracker.call(record, 'update') }
+
+puts "1. Full Tracker.call (update with only/ignore)"
+puts '-' * 50
+allocs = measure_allocs { Trakable::Tracker.call(record, 'update') }
+types = measure_allocs_by_type { Trakable::Tracker.call(record, 'update') }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts "   Breakdown: #{types.select { |_, v| v > 0 }.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+puts
+
+puts "2. Tracker.call (create, no changeset)"
+puts '-' * 50
+allocs = measure_allocs { Trakable::Tracker.call(record, 'create') }
+types = measure_allocs_by_type { Trakable::Tracker.call(record, 'create') }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts "   Breakdown: #{types.select { |_, v| v > 0 }.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+puts
+
+puts "3. Tracker.call (destroy, full object state)"
+puts '-' * 50
+allocs = measure_allocs { Trakable::Tracker.call(record, 'destroy') }
+types = measure_allocs_by_type { Trakable::Tracker.call(record, 'destroy') }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts "   Breakdown: #{types.select { |_, v| v > 0 }.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+puts
+
+puts "4. Trak.build only"
+puts '-' * 50
+allocs = measure_allocs { Trakable::Trak.build(item: record, event: 'update', changeset: {}, object: {}) }
+types = measure_allocs_by_type { Trakable::Trak.build(item: record, event: 'update', changeset: {}, object: {}) }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts "   Breakdown: #{types.select { |_, v| v > 0 }.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+puts
+
+puts "5. filter_changeset only"
+puts '-' * 50
+tracker = Trakable::Tracker.new(record, 'update')
+allocs = measure_allocs { tracker.send(:filter_changeset, record.previous_changes) }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts
+
+puts "6. build_object_from_previous only"
+puts '-' * 50
+allocs = measure_allocs { tracker.send(:build_object_from_previous) }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts
+
+# No-filter scenario
+record_no_filter = MockRecord.new
+record_no_filter.trakable_options = {}
+puts "7. Tracker.call (update, no model filters)"
+puts '-' * 50
+allocs = measure_allocs { Trakable::Tracker.call(record_no_filter, 'update') }
+puts "   Allocations per call: #{allocs.round(1)}"
+puts
+
+puts '=' * 60
+puts 'Memory Benchmark Complete'
+puts '=' * 60

data/benchmark/perf_benchmark.rb

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Performance Benchmark for Trakable
+# Measures tracking overhead for common operations
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'trakable'
+require 'benchmark'
+
+puts "=" * 60
+puts "Trakable Performance Benchmark"
+puts "=" * 60
+puts
+
+# Configuration
+ITERATIONS = 50_000
+
+# Test 1: Filter changeset with only + ignore
+puts "Test 1: filter_changeset with only/ignore (#{ITERATIONS} iterations)"
+puts "-" * 50
+
+# Simulate a record with trakable_options
+class MockRecord
+  attr_accessor :trakable_options
+
+  def previous_changes
+    @previous_changes ||= {
+      'title' => ['Old Title', 'New Title'],
+      'body' => ['Old Body', 'New Body'],
+      'views' => [0, 10],
+      'updated_at' => [Time.now - 3600, Time.now],
+      'status' => ['draft', 'published']
+    }
+  end
+end
+
+record = MockRecord.new
+record.trakable_options = { only: %i[title body], ignore: %i[status] }
+
+tracker = Trakable::Tracker.new(record, 'update')
+
+time = Benchmark.realtime do
+  ITERATIONS.times { tracker.send(:filter_changeset, record.previous_changes.dup) }
+end
+
+puts "Time: #{(time * 1000).round(2)}ms"
+puts "Per iteration: #{(time / ITERATIONS * 1_000_000).round(2)}µs"
+baseline_filter = time
+puts
+
+# Test 2: Filter changeset without only/ignore (fast path)
+puts "Test 2: filter_changeset without filters (#{ITERATIONS} iterations)"
+puts "-" * 50
+
+record2 = MockRecord.new
+record2.trakable_options = {}
+tracker2 = Trakable::Tracker.new(record2, 'update')
+
+time = Benchmark.realtime do
+  ITERATIONS.times { tracker2.send(:filter_changeset, record2.previous_changes.dup) }
+end
+
+puts "Time: #{(time * 1000).round(2)}ms"
+puts "Per iteration: #{(time / ITERATIONS * 1_000_000).round(2)}µs"
+puts
+
+# Test 3: String conversion overhead
+puts "Test 3: Array().map(&:to_s) overhead (#{ITERATIONS} iterations)"
+puts "-" * 50
+
+only_symbols = %i[title body views status]
+only_strings = %w[title body views status]
+
+time_symbols = Benchmark.realtime do
+  ITERATIONS.times { Array(only_symbols).map(&:to_s) }
+end
+
+time_strings = Benchmark.realtime do
+  ITERATIONS.times { Array(only_strings).map(&:to_s) }
+end
+
+puts "Symbols: #{(time_symbols * 1000).round(2)}ms"
+puts "Pre-converted strings: #{(time_strings * 1000).round(2)}ms"
+puts "Speedup: #{(time_symbols / time_strings).round(2)}x"
+puts
+
+# Test 4: Set vs Array for ignore lookups
+puts "Test 4: Set vs Array for ignore lookups (#{ITERATIONS} iterations)"
+puts "-" * 50
+
+ignore_array = %w[updated_at created_at id views status]
+ignore_set = ignore_array.to_set
+keys = %w[title body views status updated_at created_at id]
+
+time_array = Benchmark.realtime do
+  ITERATIONS.times { keys.reject { |k| ignore_array.include?(k) } }
+end
+
+time_set = Benchmark.realtime do
+  ITERATIONS.times { keys.reject { |k| ignore_set.include?(k) } }
+end
+
+puts "Array#include?: #{(time_array * 1000).round(2)}ms"
+puts "Set#include?: #{(time_set * 1000).round(2)}ms"
+puts "Speedup: #{(time_array / time_set).round(2)}x"
+puts
+
+# Test 5: respond_to? vs direct check
+puts "Test 5: respond_to? overhead (#{ITERATIONS} iterations)"
+puts "-" * 50
+
+obj = Object.new
+
+time_respond = Benchmark.realtime do
+  ITERATIONS.times { obj.respond_to?(:trakable_options) }
+end
+
+time_direct = Benchmark.realtime do
+  ITERATIONS.times { obj.is_a?(MockRecord) }
+end
+
+puts "respond_to?: #{(time_respond * 1000).round(2)}ms"
+puts "is_a?: #{(time_direct * 1000).round(2)}ms"
+puts
+
+puts "=" * 60
+puts "Benchmark Complete"
+puts "Baseline filter_changeset: #{(baseline_filter / ITERATIONS * 1_000_000).round(2)}µs per call"
+puts "=" * 60

data/integration/README.md

@@ -0,0 +1,65 @@
+# Trakable Integration Tests
+
+## Overview
+
+Integration tests simulate real-world usage scenarios of the Trakable gem. Each scenario tests a complete feature or workflow from start to finish.
+
+## Running Tests
+
+```bash
+# Run all integration scenarios
+ruby integration/run_all.rb
+
+# Run a specific scenario
+ruby integration/scenarios/01-basic-tracking/scenario.rb
+```
+
+## Scenarios
+
+| # | Scenario | Description |
+|---|----------|-------------|
+| 01 | Basic Tracking | Tests create/update/destroy tracking |
+| 02 | Revert & Restoration | Tests revert! and reify functionality |
+| 03 | Whodunnit Tracking | Tests polymorphic whodunnit and context |
+| 04 | Cleanup & Retention | Tests max_traks and retention policies |
+| 05 | Without Tracking | Tests skipping tracking |
+
+## Creating a New Scenario
+
+1. Create a new directory: `integration/scenarios/NN-description/`
+2. Create `scenario.rb` with your test code
+3. Include the scenario runner:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative '../scenario_runner'
+
+run_scenario 'My Scenario Name' do
+  puts '=== Scenario NN: My Scenario Name ==='
+
+  # Your test code here
+
+  puts '=== Scenario NN PASSED ✓ ==='
+end
+```
+
+## Scenario Structure
+
+Each scenario should:
+- Be self-contained and runnable independently
+- Clean up after itself (reset context, etc.)
+- Print clear progress messages
+- Use assertions to verify behavior
+- Handle exceptions gracefully
+
+## Available Assertions
+
+```ruby
+assert(condition, message)
+assert_equal(expected, actual)
+assert_kind_of(Class, object)
+assert_includes(collection, item)
+refute(condition, message)
+refute_nil(object)
+```

data/integration/run_all.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Trakable Integration Test Runner
+# Runs all scenario tests in order
+
+puts '=' * 70
+puts 'TRAKABLE INTEGRATION TESTS'
+puts '=' * 70
+puts
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'trakable'
+require 'minitest/autorun'
+
+# Reset context before tests
+Trakable::Context.reset!
+
+# Track results
+results = { passed: 0, failed: 0, errors: [] }
+
+# Run each scenario
+scenarios_dir = File.expand_path('scenarios', __dir__)
+scenario_dirs = Dir.glob("#{scenarios_dir}/*").select { |d| File.directory?(d) }.sort
+
+scenario_dirs.each do |dir|
+  scenario_file = File.join(dir, 'scenario.rb')
+  next unless File.exist?(scenario_file)
+
+  puts "\n#{'=' * 70}"
+  puts "Running: #{File.basename(dir)}"
+  puts '=' * 70
+
+  begin
+    load scenario_file
+    results[:passed] += 1
+  rescue StandardError => e
+    results[:failed] += 1
+    results[:errors] << { scenario: File.basename(dir), error: e.message }
+  end
+
+  # Reset context between scenarios
+  Trakable::Context.reset!
+end
+
+# Summary
+puts "\n#{'=' * 70}"
+puts 'INTEGRATION TEST SUMMARY'
+puts '=' * 70
+puts "Passed: #{results[:passed]}"
+puts "Failed: #{results[:failed]}"
+
+if results[:errors].any?
+  puts "\nFailures:"
+  results[:errors].each do |error|
+    puts "  - #{error[:scenario]}: #{error[:error]}"
+  end
+  exit 1
+else
+  puts "\nAll integration tests passed! ✓"
+  exit 0
+end