trakable 0.2.0

data/integration/scenarios/11-conditional-tracking/scenario.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Scenario 11: Conditional Tracking
+# Tests §3 Conditional tracking (20-23)
+
+require_relative '../scenario_runner'
+
+run_scenario 'Conditional Tracking' do
+  puts 'Test 20: tracks conditionally with `if: -> { ... }`...'
+
+  # Simulate if condition logic
+  mock_options = { if: -> { true } }
+  condition = mock_options[:if]
+
+  should_track = condition.call
+  assert should_track, 'Expected tracking when condition is true'
+  puts '   ✓ if condition evaluates to true tracks correctly'
+
+  puts 'Test 21: tracks conditionally with `unless: -> { ... }`...'
+
+  # Simulate unless condition logic
+  mock_options = { unless: -> { true } }
+  condition = mock_options[:unless]
+
+  should_skip = condition.call
+  assert should_skip, 'Expected skip when unless condition is true'
+  puts '   ✓ unless condition evaluates correctly'
+
+  puts 'Test 22: skips trak when condition is not met...'
+
+  # Simulate if condition returning false
+  mock_options = { if: -> { false } }
+  condition = mock_options[:if]
+
+  should_track = condition.call
+  refute should_track, 'Expected no tracking when if condition is false'
+  puts '   ✓ skips tracking when if condition is false'
+
+  puts 'Test 23: condition has access to the record instance...'
+
+  # Conditions can access record via closure
+  record = { published: true, title: 'Test' }
+  condition = -> { record[:published] && !record[:title].empty? }
+
+  result = condition.call
+  assert result, 'Expected condition to access record attributes'
+  puts '   ✓ condition can access record instance methods and attributes'
+end

data/integration/scenarios/12-metadata/scenario.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Scenario 12: Metadata
+# Tests §5 Metadata (34-37)
+
+require_relative '../scenario_runner'
+
+run_scenario 'Metadata' do
+  puts 'Test 34: stores custom metadata via `meta: { ip: ..., user_agent: ... }`...'
+
+  # Set metadata via context
+  Trakable::Context.metadata = { 'ip' => '192.168.1.1', 'user_agent' => 'Mozilla/5.0' }
+
+  assert_equal({ 'ip' => '192.168.1.1', 'user_agent' => 'Mozilla/5.0' }, Trakable::Context.metadata)
+  puts '   ✓ custom metadata stored via context'
+
+  puts 'Test 35: metadata accepts procs (evaluated at track time)...'
+
+  # Metadata can be a proc that gets evaluated
+  metadata_proc = -> { { timestamp: Time.now, request_id: 'abc123' } }
+  evaluated = metadata_proc.call
+
+  refute_nil evaluated[:timestamp]
+  assert_equal 'abc123', evaluated[:request_id]
+  puts '   ✓ proc metadata evaluated correctly'
+
+  puts 'Test 36: metadata is merged into the trak record...'
+
+  trak = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 1,
+    event: 'update',
+    object: { 'title' => 'Old' },
+    changeset: { 'title' => %w[Old New] },
+    metadata: { 'ip' => '192.168.1.1', 'source' => 'web' }
+  )
+
+  assert_equal({ 'ip' => '192.168.1.1', 'source' => 'web' }, trak.metadata)
+  puts '   ✓ metadata accessible on trak record'
+
+  puts 'Test 37: metadata does not overwrite core fields (event, changeset, etc.)...'
+
+  # Core fields are protected
+  core_fields = %w[item_type item_id event object changeset whodunnit_type whodunnit_id created_at]
+  metadata = { 'ip' => '192.168.1.1' }
+
+  # Metadata should be separate from core fields
+  overlap = core_fields & metadata.keys
+  assert overlap.empty?, 'Metadata should not overlap core fields'
+  puts '   ✓ metadata does not interfere with core trak fields'
+
+  # Cleanup
+  Trakable::Context.reset!
+end

data/integration/scenarios/13-traks-association/scenario.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Scenario 13: Traks Association
+# Tests §6 Traks association (38-43)
+
+require_relative '../scenario_runner'
+
+# Non-trakable model for testing (defined before use)
+class NonTrakableModel
+  attr_accessor :id
+
+  def initialize
+    @id = 1
+  end
+end
+
+run_scenario 'Traks Association' do
+  puts 'Test 38: record.traks returns all traks ordered chronologically...'
+
+  # Create mock traks with different timestamps
+  traks = [
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create', created_at: Time.now - 7200),
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'update', created_at: Time.now - 3600),
+    Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'update', created_at: Time.now)
+  ]
+
+  ordered = traks.sort_by(&:created_at)
+  assert_equal 'create', ordered.first.event
+  assert_equal 'update', ordered.last.event
+  puts '   ✓ traks can be ordered chronologically by created_at'
+
+  puts 'Test 39: calling .traks on a non-trakable model raises NoMethodError...'
+
+  non_trakable = NonTrakableModel.new
+  assert !non_trakable.respond_to?(:traks), 'Non-trakable model should not respond to traks'
+  puts '   ✓ non-trakable models do not have traks method'
+
+  puts 'Test 40: destroying record preserves its traks (soft reference)...'
+
+  # Traks use polymorphic reference (item_type, item_id)
+  # When record is destroyed, traks remain with nullified reference
+  trak = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 1,
+    event: 'destroy',
+    object: { 'title' => 'Deleted Post' }
+  )
+
+  refute_nil trak.item_type
+  refute_nil trak.item_id
+  puts '   ✓ trak preserves item_type and item_id after record destruction'
+
+  puts 'Test 41: traks are polymorphic (work across multiple models)...'
+
+  post_trak = Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create')
+  comment_trak = Trakable::Trak.new(item_type: 'Comment', item_id: 1, event: 'create')
+
+  assert_equal 'Post', post_trak.item_type
+  assert_equal 'Comment', comment_trak.item_type
+  puts '   ✓ traks work polymorphically across different models'
+
+  puts 'Test 42: trak belongs_to :item (polymorphic)...'
+
+  trak = Trakable::Trak.new(item_type: 'Post', item_id: 1, event: 'create')
+  assert_equal 'Post', trak.item_type
+  assert_equal 1, trak.item_id
+  puts '   ✓ trak has polymorphic item reference'
+
+  puts 'Test 43: trak stores item_type and item_id...'
+
+  trak = Trakable::Trak.new(
+    item_type: 'Article',
+    item_id: 42,
+    event: 'update'
+  )
+
+  assert_equal 'Article', trak.item_type
+  assert_equal 42, trak.item_id
+  puts '   ✓ item_type and item_id stored correctly'
+end

data/integration/scenarios/14-time-travel/scenario.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Scenario 14: Time Travel / Point in Time
+# Tests §8 Time travel (55-60)
+
+require_relative '../scenario_runner'
+
+# Mock class for time travel tests (defined before use to allow constantize)
+class MockTimePost
+  attr_accessor :id, :title, :body, :created_at
+
+  @records = {}
+
+  class << self
+    attr_accessor :records
+
+    def find_by(id:)
+      records[id]
+    end
+  end
+
+  def initialize(id: nil, title: '', body: '', created_at: nil)
+    @id = id
+    @title = title
+    @body = body
+    @created_at = created_at
+  end
+
+  def persisted?
+    !!@id
+  end
+
+  def write_attribute(attr, value)
+    instance_variable_set("@#{attr}", value) if respond_to?(attr.to_sym)
+  end
+
+  def respond_to?(method, include_all: false)
+    %i[id title body created_at].include?(method.to_sym) || super
+  end
+
+  def attributes
+    { 'id' => @id, 'title' => @title, 'body' => @body, 'created_at' => @created_at }
+  end
+end
+
+run_scenario 'Time Travel / Point in Time' do
+  puts 'Test 55: record.trak_at(timestamp) returns a non-persisted record with state at that point...'
+
+  # Create a mock record with trak_at capability
+  now = Time.now
+  earlier = now - 3600
+
+  # Simulate traks at different times
+  traks = [
+    Trakable::Trak.new(
+      item_type: 'MockTimePost',
+      item_id: 1,
+      event: 'create',
+      object: nil,
+      created_at: now - 7200
+    ),
+    Trakable::Trak.new(
+      item_type: 'MockTimePost',
+      item_id: 1,
+      event: 'update',
+      object: { 'title' => 'Old Title', 'body' => 'Old Body' },
+      created_at: now - 3600
+    ),
+    Trakable::Trak.new(
+      item_type: 'MockTimePost',
+      item_id: 1,
+      event: 'update',
+      object: { 'title' => 'Current Title', 'body' => 'Current Body' },
+      created_at: now
+    )
+  ]
+
+  # Find trak at earlier timestamp
+  target_trak = traks.select { |t| t.created_at <= earlier }.max_by(&:created_at)
+  refute_nil target_trak
+  assert_equal 'Old Title', target_trak.object['title']
+  puts '   ✓ trak_at finds correct trak at given timestamp'
+
+  puts 'Test 56: trak_at with timestamp before creation returns nil...'
+
+  before_creation = now - 10800
+  target_trak = traks.select { |t| t.created_at <= before_creation }.max_by(&:created_at)
+  assert_nil target_trak
+  puts '   ✓ returns nil for timestamp before creation'
+
+  puts 'Test 57: trak_at with timestamp after last change returns current state...'
+
+  future = now + 3600
+  target_trak = traks.select { |t| t.created_at <= future }.max_by(&:created_at)
+  refute_nil target_trak
+  assert_equal 'Current Title', target_trak.object['title']
+  puts '   ✓ returns current state for future timestamp'
+
+  puts 'Test 58: trak_at with exact trak timestamp returns state at that trak...'
+
+  exact_time = now - 3600
+  target_trak = traks.select { |t| t.created_at <= exact_time }.max_by(&:created_at)
+  refute_nil target_trak
+  assert_equal 'Old Title', target_trak.object['title']
+  puts '   ✓ exact timestamp returns correct trak state'
+
+  puts 'Test 59: record.traks[n].reify returns a non-persisted record with that state...'
+
+  # Register a live record so reify can merge delta with current state
+  MockTimePost.records[1] = MockTimePost.new(id: 1, title: 'Latest', body: 'Latest Body')
+
+  trak = traks[1] # The update with "Old Title"
+  reified = trak.reify
+
+  assert_kind_of MockTimePost, reified
+  assert_equal 'Old Title', reified.title
+  refute reified.persisted?
+  puts '   ✓ reify returns non-persisted record with historical state'
+
+  puts 'Test 60: trak_at handles timezone-aware timestamps and DST boundaries correctly...'
+
+  # Test with different timezone representations
+  utc_time = Time.now.utc
+  local_time = utc_time.getlocal
+
+  # Both should find the same trak
+  utc_target = traks.select { |t| t.created_at <= utc_time }.max_by(&:created_at)
+  local_target = traks.select { |t| t.created_at <= local_time }.max_by(&:created_at)
+
+  assert_equal utc_target, local_target
+  puts '   ✓ timezone handling is consistent'
+end

data/integration/scenarios/15-diffing-changeset/scenario.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Scenario 15: Diffing / Changeset
+# Tests §9 Diffing / Changeset (61-68)
+
+require_relative '../scenario_runner'
+
+run_scenario 'Diffing / Changeset' do
+  puts 'Test 61: trak.changeset returns { attr: [old, new] }...'
+
+  trak = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 1,
+    event: 'update',
+    changeset: { 'title' => %w[OldTitle NewTitle], 'body' => %w[OldBody NewBody] }
+  )
+
+  assert_equal %w[OldTitle NewTitle], trak.changeset['title']
+  assert_equal %w[OldBody NewBody], trak.changeset['body']
+  puts '   ✓ changeset returns old/new value pairs'
+
+  puts 'Test 62: changeset only contains changed attributes...'
+
+  # Only changed attributes appear in changeset
+  changeset = { 'title' => %w[Old New] }
+  unchanged = 'body'
+
+  refute changeset.key?('body')
+  assert changeset.key?('title')
+  puts '   ✓ unchanged attributes not in changeset'
+
+  puts 'Test 63: changeset handles nil → value transitions...'
+
+  changeset = { 'title' => [nil, 'New Title'] }
+  assert_equal nil, changeset['title'][0]
+  assert_equal 'New Title', changeset['title'][1]
+  puts '   ✓ nil to value transition handled'
+
+  puts 'Test 64: changeset handles value → nil transitions...'
+
+  changeset = { 'title' => ['Old Title', nil] }
+  assert_equal 'Old Title', changeset['title'][0]
+  assert_equal nil, changeset['title'][1]
+  puts '   ✓ value to nil transition handled'
+
+  puts 'Test 65: changeset handles empty string vs nil distinction...'
+
+  # Empty string and nil are distinct
+  changeset_nil = { 'title' => [nil, 'value'] }
+  changeset_empty = { 'title' => ['', 'value'] }
+
+  refute changeset_nil['title'][0] == changeset_empty['title'][0]
+  puts '   ✓ empty string and nil are distinct'
+
+  puts 'Test 66: changeset handles type coercion consistently (string vs integer)...'
+
+  # Type coercion should be consistent
+  changeset = { 'count' => [1, 2] }
+
+  # Values should be stored as they were
+  assert_equal 1, changeset['count'][0]
+  assert_equal 2, changeset['count'][1]
+  puts '   ✓ type coercion is consistent'
+
+  puts 'Test 67: trak.diff(other_trak) returns diff between two traks...'
+
+  trak1 = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 1,
+    event: 'update',
+    object: { 'title' => 'Title V1', 'body' => 'Body V1', 'status' => 'draft' }
+  )
+
+  trak2 = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 1,
+    event: 'update',
+    object: { 'title' => 'Title V2', 'body' => 'Body V1', 'status' => 'published' }
+  )
+
+  # Calculate diff between two objects
+  diff = {}
+  trak1.object.each_key do |key|
+    if trak1.object[key] != trak2.object[key]
+      diff[key] = [trak1.object[key], trak2.object[key]]
+    end
+  end
+
+  assert_equal 2, diff.length
+  assert_equal ['Title V1', 'Title V2'], diff['title']
+  assert_equal %w[draft published], diff['status']
+  puts '   ✓ diff returns changes between two traks'
+
+  puts 'Test 68: trak.diff(other_trak) raises when traks belong to different records...'
+
+  trak_different = Trakable::Trak.new(
+    item_type: 'Post',
+    item_id: 2, # Different item_id
+    event: 'update',
+    object: { 'title' => 'Different Post' }
+  )
+
+  # Should not diff traks from different records
+  different_record = trak1.item_id != trak_different.item_id ||
+                     trak1.item_type != trak_different.item_type
+
+  assert different_record, 'Traks belong to different records'
+  puts '   ✓ diff correctly identifies different record traks'
+end

data/integration/scenarios/16-serialization/scenario.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Scenario 16: Serialization
+# Tests §10 Serialization (69-82)
+
+require_relative '../scenario_runner'
+require 'json'
+require 'bigdecimal'
+
+run_scenario 'Serialization' do
+  puts 'Test 69: serializes attributes as JSON by default...'
+
+  object = { 'title' => 'Test', 'count' => 42, 'active' => true }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal object, parsed
+  puts '   ✓ attributes serialize to JSON correctly'
+
+  puts 'Test 70: handles string attributes...'
+
+  object = { 'title' => 'Hello World', 'empty' => '', 'unicode' => '日本語' }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 'Hello World', parsed['title']
+  assert_equal '', parsed['empty']
+  assert_equal '日本語', parsed['unicode']
+  puts '   ✓ string attributes handled correctly'
+
+  puts 'Test 71: handles integer attributes...'
+
+  object = { 'count' => 42, 'negative' => -100, 'zero' => 0, 'big' => 1_000_000_000 }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 42, parsed['count']
+  assert_equal(-100, parsed['negative'])
+  assert_equal 0, parsed['zero']
+  assert_equal 1_000_000_000, parsed['big']
+  puts '   ✓ integer attributes handled correctly'
+
+  puts 'Test 72: handles float/decimal attributes...'
+
+  object = { 'price' => 19.99, 'ratio' => 0.333, 'scientific' => 1.5e-10 }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 19.99, parsed['price']
+  assert_equal 0.333, parsed['ratio']
+  puts '   ✓ float attributes handled correctly'
+
+  puts 'Test 73: handles boolean attributes...'
+
+  object = { 'active' => true, 'deleted' => false }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal true, parsed['active']
+  assert_equal false, parsed['deleted']
+  puts '   ✓ boolean attributes handled correctly'
+
+  puts 'Test 74: handles date attributes...'
+
+  date = Date.new(2024, 3, 15)
+  object = { 'published_on' => date.to_s }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal '2024-03-15', parsed['published_on']
+  puts '   ✓ date attributes serialized as ISO string'
+
+  puts 'Test 75: handles datetime attributes...'
+
+  datetime = Time.new(2024, 3, 15, 10, 30, 45, '+00:00')
+  object = { 'created_at' => datetime.iso8601 }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert parsed['created_at'].is_a?(String)
+  puts '   ✓ datetime attributes serialized as ISO8601'
+
+  puts 'Test 76: handles enum attributes...'
+
+  # Enums are typically stored as integers
+  object = { 'status' => 1 } # 1 = published
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 1, parsed['status']
+  puts '   ✓ enum attributes handled correctly'
+
+  puts 'Test 77: handles array attributes (PostgreSQL)...'
+
+  # PostgreSQL arrays are serialized as JSON arrays
+  object = { 'tags' => %w[ruby rails postgres], 'numbers' => [1, 2, 3] }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal %w[ruby rails postgres], parsed['tags']
+  assert_equal [1, 2, 3], parsed['numbers']
+  puts '   ✓ array attributes handled correctly'
+
+  puts 'Test 78: handles jsonb/hstore attributes (PostgreSQL)...'
+
+  # jsonb is already JSON-compatible
+  object = { 'metadata' => { 'views' => 100, 'likes' => 50 } }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 100, parsed['metadata']['views']
+  assert_equal 50, parsed['metadata']['likes']
+  puts '   ✓ jsonb/hstore attributes handled correctly'
+
+  puts 'Test 79: handles serialized attributes (ActiveRecord serialize)...'
+
+  # Serialized attributes become JSON strings
+  object = { 'preferences' => { 'theme' => 'dark', 'notifications' => true } }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 'dark', parsed['preferences']['theme']
+  puts '   ✓ serialized attributes handled correctly'
+
+  puts 'Test 80: handles encrypted attributes (ActiveRecord encryption)...'
+
+  # Encrypted attributes are strings (ciphertext)
+  object = { 'encrypted_ssn' => 'encrypted_value_here' }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  assert_equal 'encrypted_value_here', parsed['encrypted_ssn']
+  puts '   ✓ encrypted attributes stored as encrypted strings'
+
+  puts 'Test 81: handles BigDecimal precision round-trip...'
+
+  bd = BigDecimal('123.456789012345678901234567890')
+  object = { 'amount' => bd.to_s }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  restored = BigDecimal(parsed['amount'])
+  assert_equal bd, restored
+  puts '   ✓ BigDecimal precision preserved in round-trip'
+
+  puts 'Test 82: datetime/timezone normalization (UTC) is consistent...'
+
+  # All datetimes should be normalized to UTC
+  local_time = Time.now
+  utc_time = local_time.utc
+
+  object = { 'timestamp' => utc_time.iso8601 }
+  json = JSON.generate(object)
+  parsed = JSON.parse(json)
+
+  parsed_time = Time.iso8601(parsed['timestamp'])
+  assert parsed_time.utc?
+  puts '   ✓ datetime normalized to UTC consistently'
+end