paper_trail_diff 0.1.0 → 0.2.0

data/lib/paper_trail_diff/snapshot_traversal.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Walks nested state included in an added, removed, or replaced record snapshot.
+  class SnapshotTraversal < TraversalEmitter
+    #: (RecordSnapshot, association_path: traversal_association_path, record_path: traversal_record_path, state: traversal_state, ?association_kind: Symbol?, ?include_record: bool) -> void
+    def call( # rubocop:disable Metrics/ParameterLists
+      snapshot,
+      association_path:,
+      record_path:,
+      state:,
+      association_kind: nil,
+      include_record: true
+    )
+      if include_record
+        emit_record(snapshot, association_path, record_path, state, association_kind)
+      end
+      emit_attributes(snapshot, association_path, record_path, state, association_kind)
+      emit_associations(snapshot, association_path, record_path, state)
+    end
+
+    private
+
+    #: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_record(snapshot, association_path, record_path, state, association_kind)
+      emit(
+        kind: :record_included,
+        context: :included_state,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association_kind,
+        state: state,
+        value: snapshot.reference
+      )
+    end
+
+    #: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_attributes(snapshot, association_path, record_path, state, association_kind)
+      snapshot.attributes.each do |name, value|
+        emit_attribute(name, value, association_path, record_path, state, association_kind)
+      end
+    end
+
+    #: (String, untyped, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_attribute( # rubocop:disable Metrics/ParameterLists
+      name, value, association_path, record_path, state, association_kind
+    )
+      emit(
+        kind: :attribute_included,
+        context: :included_state,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association_kind,
+        state: state,
+        attribute: name,
+        value: value
+      )
+    end
+
+    #: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_associations(snapshot, association_path, record_path, state)
+      snapshot.associations.each do |name, association|
+        child_path = association_path + [name]
+        emit_association(association, child_path, record_path, state)
+        emit_association_records(association, child_path, record_path, state)
+      end
+    end
+
+    #: (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_association(association, association_path, record_path, state)
+      emit(
+        kind: :association_included,
+        context: :included_state,
+        association_path: association_path,
+        record_path: record_path,
+        association_kind: association.kind,
+        state: state,
+        value: association
+      )
+    end
+
+    #: (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_association_records(association, association_path, record_path, state)
+      association.records.each do |snapshot|
+        call(
+          snapshot,
+          association_path: association_path,
+          record_path: record_path + [snapshot.reference],
+          state: state,
+          association_kind: association.kind
+        )
+      end
+    end
+  end
+  private_constant :SnapshotTraversal
+end

data/lib/paper_trail_diff/step.rb

@@ -6,16 +6,25 @@ module PaperTrailDiff
   class Step
     attr_reader :from_version #: untyped
     attr_reader :to_version #: untyped
+    attr_reader :from_boundary #: ActivityBoundary
+    attr_reader :to_boundary #: ActivityBoundary
     attr_reader :diff #: Diff
 
     #: (from_version: untyped, to_version: untyped, diff: Diff) -> void
     def initialize(from_version:, to_version:, diff:)
       @from_version = from_version
       @to_version = to_version
+      @from_boundary = ActivityBoundary.from_version(from_version)
+      @to_boundary = ActivityBoundary.from_version(to_version)
       @diff = diff
       freeze
     end
 
+    #: () -> bool
+    def empty?
+      diff.empty?
+    end
+
     #: () -> Hash[Symbol, untyped]
     def to_h
       {

data/lib/paper_trail_diff/traversal.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Coordinates root lifecycle, scalar, and association traversal.
+  class DiffTraversal < TraversalEmitter
+    #: (Diff, ^(TraversalEntry) -> void) -> void
+    def initialize(diff, receiver)
+      super(receiver)
+      @diff = diff
+      @associations = AssociationDiffTraversal.new(receiver)
+      @snapshots = SnapshotTraversal.new(receiver)
+    end
+
+    #: () -> void
+    def call
+      walk_presence_change
+      @associations.attributes(
+        @diff.attributes,
+        association_path: [],
+        record_path: [],
+        association_kind: nil
+      )
+      @associations.call(@diff.associations, association_path: [], record_path: [])
+    end
+
+    private
+
+    # @rbs @diff: Diff
+    # @rbs @associations: AssociationDiffTraversal
+    # @rbs @snapshots: SnapshotTraversal
+
+    #: () -> void
+    def walk_presence_change
+      change = @diff.record_presence_change
+      return unless change
+
+      emit(
+        kind: :record_presence_changed,
+        context: :change,
+        association_path: [],
+        record_path: [],
+        value: change
+      )
+      walk_presence_snapshot(change.from, :before)
+      walk_presence_snapshot(change.to, :after)
+    end
+
+    #: (RecordSnapshot?, traversal_state) -> void
+    def walk_presence_snapshot(snapshot, state)
+      return unless snapshot
+
+      @snapshots.call(snapshot, association_path: [], record_path: [], state: state)
+    end
+  end
+  private_constant :DiffTraversal
+
+  # The complete structured difference between two normalized endpoints.
+  class Diff
+    # Walks semantic changes and the nested state carried by added or removed records.
+    # @rbs () { (TraversalEntry) -> void } -> Diff
+    #    | () -> Enumerator[TraversalEntry, Diff]
+    def each_entry(&receiver)
+      return enum_for(:each_entry) unless receiver
+
+      DiffTraversal.new(self, receiver).call
+      self
+    end
+
+    # Walks only semantic changes, excluding snapshot state included for context.
+    # @rbs () { (TraversalEntry) -> void } -> Diff
+    #    | () -> Enumerator[TraversalEntry, Diff]
+    def each_change(&receiver)
+      return enum_for(:each_change) unless receiver
+
+      each_entry { |entry| receiver.call(entry) if entry.change? }
+      self
+    end
+  end
+end

data/lib/paper_trail_diff/traversal_emitter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # Shared entry construction for internal traversal collaborators.
+  class TraversalEmitter
+    #: (^(TraversalEntry) -> void) -> void
+    def initialize(receiver)
+      @receiver = receiver
+    end
+
+    private
+
+    # @rbs @receiver: ^(TraversalEntry) -> void
+
+    #: (kind: Symbol, context: traversal_context, association_path: traversal_association_path, record_path: traversal_record_path, value: untyped, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?) -> void
+    def emit( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      context:,
+      association_path:,
+      record_path:,
+      value:,
+      association_kind: nil,
+      state: nil,
+      attribute: nil
+    )
+      @receiver.call(
+        TraversalEntry.new(
+          kind: kind,
+          context: context,
+          association_path: association_path,
+          record_path: record_path,
+          association_kind: association_kind,
+          state: state,
+          attribute: attribute,
+          value: value
+        )
+      )
+    end
+  end
+  private_constant :TraversalEmitter
+end

data/lib/paper_trail_diff/traversal_entry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module PaperTrailDiff
+  # One immutable location and value emitted while walking a Diff tree.
+  class TraversalEntry
+    CONTEXTS = %i[change included_state].freeze
+    STATES = %i[before after].freeze
+    private_constant :CONTEXTS, :STATES
+
+    attr_reader :kind #: Symbol
+    attr_reader :context #: traversal_context
+    attr_reader :association_path #: traversal_association_path
+    attr_reader :record_path #: traversal_record_path
+    attr_reader :association_kind #: Symbol?
+    attr_reader :state #: traversal_state?
+    attr_reader :attribute #: String?
+    attr_reader :value #: untyped
+
+    #: (kind: Symbol, context: traversal_context, ?association_path: traversal_association_path, ?record_path: traversal_record_path, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?, ?value: untyped) -> void
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      kind:,
+      context:,
+      association_path: [],
+      record_path: [],
+      association_kind: nil,
+      state: nil,
+      attribute: nil,
+      value: nil
+    )
+      validate!(context, state)
+      @kind = kind
+      @context = context
+      @association_path = immutable_names(association_path)
+      @record_path = Support.immutable_copy(record_path)
+      @association_kind = association_kind
+      @state = state
+      @attribute = Support.immutable_copy(attribute&.to_s)
+      @value = Support.immutable_copy(value)
+      freeze
+    end
+
+    #: () -> bool
+    def change?
+      context == :change
+    end
+
+    #: () -> bool
+    def included_state?
+      context == :included_state
+    end
+
+    #: () -> String?
+    def association
+      association_path.last
+    end
+
+    #: () -> RecordReference?
+    def record
+      record_path.last
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        kind: kind,
+        context: context,
+        association_path: Support.serialize(association_path),
+        record_path: Support.serialize(record_path),
+        association_kind: association_kind,
+        state: state,
+        attribute: attribute,
+        value: Support.serialize(value)
+      }
+    end
+
+    private
+
+    #: (Symbol, Symbol?) -> void
+    def validate!(candidate_context, candidate_state)
+      unless CONTEXTS.include?(candidate_context)
+        raise ArgumentError, "unsupported traversal context: #{candidate_context.inspect}"
+      end
+      return if candidate_state.nil? || STATES.include?(candidate_state)
+
+      raise ArgumentError, "unsupported traversal state: #{candidate_state.inspect}"
+    end
+
+    #: (traversal_association_path) -> traversal_association_path
+    def immutable_names(names)
+      names.map { |name| Support.immutable_copy(name.to_s) }.freeze
+    end
+  end
+end

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/paper_trail_diff.rb

@@ -13,6 +13,11 @@ require_relative 'paper_trail_diff/association_discovery'
 require_relative 'paper_trail_diff/diagnostics'
 require_relative 'paper_trail_diff/snapshot'
 require_relative 'paper_trail_diff/value_objects'
+require_relative 'paper_trail_diff/traversal_entry'
+require_relative 'paper_trail_diff/traversal_emitter'
+require_relative 'paper_trail_diff/snapshot_traversal'
+require_relative 'paper_trail_diff/association_diff_traversal'
+require_relative 'paper_trail_diff/traversal'
 require_relative 'paper_trail_diff/engine'
 require_relative 'paper_trail_diff/historical_association_reifier'
 require_relative 'paper_trail_diff/prepared_record_index'
@@ -27,8 +32,8 @@ require_relative 'paper_trail_diff/timeline_snapshot_provider'
 require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
 require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
 require_relative 'paper_trail_diff/branch_snapshot_refresher'
-require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/activity_boundary'
+require_relative 'paper_trail_diff/step'
 require_relative 'paper_trail_diff/analysis'
 require_relative 'paper_trail_diff/version_range'
 require_relative 'paper_trail_diff/timeline_builder'
@@ -50,6 +55,10 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
 #     type identity = Array[untyped]
 #     type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 #     type reference_key = :type | :id | "type" | "id"
+#     type traversal_context = :change | :included_state
+#     type traversal_state = :before | :after
+#     type traversal_association_path = Array[String]
+#     type traversal_record_path = Array[RecordReference]
 #   end
 
 # Structured version comparison for PaperTrail.

data/sig/generated/paper_trail_diff/activity_boundary.rbs

@@ -13,14 +13,26 @@ module PaperTrailDiff
 
     attr_reader recorded_at: untyped
 
+    attr_reader event: String?
+
+    attr_reader whodunnit: untyped
+
+    attr_reader record: RecordReference
+
     # : (untyped) -> ActivityBoundary
     def self.from_version: (untyped) -> ActivityBoundary
 
     # : (untyped, captured_at: untyped) -> ActivityBoundary
     def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
 
-    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
-    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped) -> void
+    # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+    def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped) -> void
+
+    # : () -> bool
+    def version?: () -> bool
+
+    # : () -> bool
+    def current?: () -> bool
 
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
@@ -37,6 +49,9 @@ module PaperTrailDiff
     # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
     def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff) -> void
 
+    # : () -> bool
+    def empty?: () -> bool
+
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/association_diff_traversal.rbs

@@ -0,0 +1,58 @@
+# Generated from lib/paper_trail_diff/association_diff_traversal.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Walks nested singular and collection association differences.
+  class AssociationDiffTraversal < TraversalEmitter
+    # : (^(TraversalEntry) -> void) -> void
+    def initialize: (^(TraversalEntry) -> void) -> void
+
+    # : (association_diffs, association_path: traversal_association_path, record_path: traversal_record_path) -> void
+    def call: (association_diffs, association_path: traversal_association_path, record_path: traversal_record_path) -> void
+
+    # : (Hash[String, ValueChange], association_path: traversal_association_path, record_path: traversal_record_path, association_kind: Symbol?) -> void
+    def attributes: (Hash[String, ValueChange], association_path: traversal_association_path, record_path: traversal_record_path, association_kind: Symbol?) -> void
+
+    private
+
+    @snapshots: SnapshotTraversal
+
+    # : (association_diff, traversal_association_path, traversal_record_path) -> void
+    def walk_association: (association_diff, traversal_association_path, traversal_record_path) -> void
+
+    # : (String, ValueChange, traversal_association_path, traversal_record_path, Symbol?) -> void
+    def emit_attribute: (String, ValueChange, traversal_association_path, traversal_record_path, Symbol?) -> void
+
+    # : (CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_collection: (CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+
+    # : (Array[RecordSnapshot], Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_memberships: (Array[RecordSnapshot], Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+
+    # : (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_membership: (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+
+    # : (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def emit_membership: (RecordSnapshot, Symbol, traversal_state, CollectionAssociationDiff, traversal_association_path, traversal_record_path) -> void
+
+    # : (ToOneAssociationDiff, traversal_association_path, traversal_record_path) -> void
+    def walk_to_one: (ToOneAssociationDiff, traversal_association_path, traversal_record_path) -> void
+
+    # : (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_relationship: (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+
+    # : (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def emit_relationship: (ValueChange, Symbol, traversal_association_path, traversal_record_path) -> void
+
+    # : (RecordSnapshot?, traversal_state, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_related: (RecordSnapshot?, traversal_state, Symbol, traversal_association_path, traversal_record_path) -> void
+
+    # : (ValueChange) -> Symbol
+    def relationship_kind: (ValueChange) -> Symbol
+
+    # : (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def walk_record_change: (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+
+    # : (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+    def emit_record_change: (RecordChange, Symbol, traversal_association_path, traversal_record_path) -> void
+  end
+end

data/sig/generated/paper_trail_diff/snapshot_traversal.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/paper_trail_diff/snapshot_traversal.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Walks nested state included in an added, removed, or replaced record snapshot.
+  class SnapshotTraversal < TraversalEmitter
+    # : (RecordSnapshot, association_path: traversal_association_path, record_path: traversal_record_path, state: traversal_state, ?association_kind: Symbol?, ?include_record: bool) -> void
+    def call: (RecordSnapshot, association_path: traversal_association_path, record_path: traversal_record_path, state: traversal_state, ?association_kind: Symbol?, ?include_record: bool) -> void
+
+    private
+
+    # : (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_record: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+
+    # : (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_attributes: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+
+    # : (String, untyped, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+    def emit_attribute: (String, untyped, traversal_association_path, traversal_record_path, traversal_state, Symbol?) -> void
+
+    # : (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_associations: (RecordSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+
+    # : (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_association: (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+
+    # : (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+    def emit_association_records: (AssociationSnapshot, traversal_association_path, traversal_record_path, traversal_state) -> void
+  end
+end

data/sig/generated/paper_trail_diff/step.rbs

@@ -7,11 +7,18 @@ module PaperTrailDiff
 
     attr_reader to_version: untyped
 
+    attr_reader from_boundary: ActivityBoundary
+
+    attr_reader to_boundary: ActivityBoundary
+
     attr_reader diff: Diff
 
     # : (from_version: untyped, to_version: untyped, diff: Diff) -> void
     def initialize: (from_version: untyped, to_version: untyped, diff: Diff) -> void
 
+    # : () -> bool
+    def empty?: () -> bool
+
     # : () -> Hash[Symbol, untyped]
     def to_h: () -> Hash[Symbol, untyped]
   end

data/sig/generated/paper_trail_diff/traversal.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/paper_trail_diff/traversal.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Coordinates root lifecycle, scalar, and association traversal.
+  class DiffTraversal < TraversalEmitter
+    # : (Diff, ^(TraversalEntry) -> void) -> void
+    def initialize: (Diff, ^(TraversalEntry) -> void) -> void
+
+    # : () -> void
+    def call: () -> void
+
+    private
+
+    @associations: AssociationDiffTraversal
+
+    @diff: Diff
+
+    @snapshots: SnapshotTraversal
+
+    # : () -> void
+    def walk_presence_change: () -> void
+
+    # : (RecordSnapshot?, traversal_state) -> void
+    def walk_presence_snapshot: (RecordSnapshot?, traversal_state) -> void
+  end
+
+  # The complete structured difference between two normalized endpoints.
+  class Diff
+    # Walks semantic changes and the nested state carried by added or removed records.
+    # @rbs () { (TraversalEntry) -> void } -> Diff
+    #    | () -> Enumerator[TraversalEntry, Diff]
+    def each_entry: () { (TraversalEntry) -> void } -> Diff
+                  | () -> Enumerator[TraversalEntry, Diff]
+
+    # Walks only semantic changes, excluding snapshot state included for context.
+    # @rbs () { (TraversalEntry) -> void } -> Diff
+    #    | () -> Enumerator[TraversalEntry, Diff]
+    def each_change: () { (TraversalEntry) -> void } -> Diff
+                   | () -> Enumerator[TraversalEntry, Diff]
+  end
+end

data/sig/generated/paper_trail_diff/traversal_emitter.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/paper_trail_diff/traversal_emitter.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Shared entry construction for internal traversal collaborators.
+  class TraversalEmitter
+    # : (^(TraversalEntry) -> void) -> void
+    def initialize: (^(TraversalEntry) -> void) -> void
+
+    private
+
+    @receiver: ^(TraversalEntry) -> void
+
+    # : (kind: Symbol, context: traversal_context, association_path: traversal_association_path, record_path: traversal_record_path, value: untyped, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?) -> void
+    def emit: (kind: Symbol, context: traversal_context, association_path: traversal_association_path, record_path: traversal_record_path, value: untyped, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?) -> void
+  end
+end

data/sig/generated/paper_trail_diff/traversal_entry.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/paper_trail_diff/traversal_entry.rb with RBS::Inline
+
+module PaperTrailDiff
+  # One immutable location and value emitted while walking a Diff tree.
+  class TraversalEntry
+    CONTEXTS: untyped
+
+    STATES: untyped
+
+    attr_reader kind: Symbol
+
+    attr_reader context: traversal_context
+
+    attr_reader association_path: traversal_association_path
+
+    attr_reader record_path: traversal_record_path
+
+    attr_reader association_kind: Symbol?
+
+    attr_reader state: traversal_state?
+
+    attr_reader attribute: String?
+
+    attr_reader value: untyped
+
+    # : (kind: Symbol, context: traversal_context, ?association_path: traversal_association_path, ?record_path: traversal_record_path, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?, ?value: untyped) -> void
+    def initialize: (kind: Symbol, context: traversal_context, ?association_path: traversal_association_path, ?record_path: traversal_record_path, ?association_kind: Symbol?, ?state: traversal_state?, ?attribute: String?, ?value: untyped) -> void
+
+    # : () -> bool
+    def change?: () -> bool
+
+    # : () -> bool
+    def included_state?: () -> bool
+
+    # : () -> String?
+    def association: () -> String?
+
+    # : () -> RecordReference?
+    def record: () -> RecordReference?
+
+    # : () -> Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+
+    private
+
+    # : (Symbol, Symbol?) -> void
+    def validate!: (Symbol, Symbol?) -> void
+
+    # : (traversal_association_path) -> traversal_association_path
+    def immutable_names: (traversal_association_path) -> traversal_association_path
+  end
+end

data/sig/generated/paper_trail_diff.rbs

@@ -53,4 +53,12 @@ module PaperTrailDiff
   type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
 
   type reference_key = :type | :id | "type" | "id"
+
+  type traversal_context = :change | :included_state
+
+  type traversal_state = :before | :after
+
+  type traversal_association_path = Array[String]
+
+  type traversal_record_path = Array[RecordReference]
 end