paper_trail_diff 0.13.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -30,22 +30,26 @@ module PaperTrailDiff
30
30
 
31
31
  # Builds activity steps while retaining root snapshots for combined analysis.
32
32
  class ActivityHistoryBuilder
33
- #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
33
+ # `closing` is the snapshot after the last event when the range closes on
34
+ # the current record. Any other range ends at a root event, or at events
35
+ # after a window whose steps are not reported, so nothing reads it.
36
+ #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
34
37
  def initialize( # rubocop:disable Metrics/ParameterLists
35
- root_versions, events, snapshotter, current: nil, include_step: nil, snapshots: false
38
+ root_versions, events, snapshotter, view:, current: nil, include_step: nil, closing: nil
36
39
  )
37
40
  @root_versions = root_versions
38
41
  @events = events
39
42
  @snapshotter = snapshotter
43
+ @view = view
40
44
  @current = current
41
45
  @include_step = include_step
42
- @snapshots = snapshots
46
+ @closing = closing
43
47
  end
44
48
 
45
49
  #: () -> ActivityHistory
46
50
  def call
47
51
  reset
48
- sequence.each { |event, snapshot| consume(event, snapshot) }
52
+ filter.call(sequence) { |event, snapshot, kept| consume(event, snapshot, kept) }
49
53
  ActivityHistory.new(
50
54
  steps: @steps,
51
55
  root_snapshots: @root_snapshots,
@@ -63,7 +67,8 @@ module PaperTrailDiff
63
67
  # @rbs @snapshotter: untyped
64
68
  # @rbs @current: untyped
65
69
  # @rbs @include_step: untyped
66
- # @rbs @snapshots: bool
70
+ # @rbs @view: ActivityView
71
+ # @rbs @closing: RecordSnapshot?
67
72
  # @rbs @steps: Array[ActivityStep]
68
73
  # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
69
74
  # @rbs @first_snapshot: RecordSnapshot?
@@ -71,6 +76,7 @@ module PaperTrailDiff
71
76
  # @rbs @selected_last_snapshot: RecordSnapshot?
72
77
  # @rbs @previous_boundary: ActivityBoundary?
73
78
  # @rbs @previous_event: ActivityEvent?
79
+ # @rbs @passed_reported: bool
74
80
 
75
81
  #: () -> void
76
82
  def reset
@@ -82,6 +88,12 @@ module PaperTrailDiff
82
88
  @selected_last_snapshot = nil
83
89
  @previous_boundary = nil
84
90
  @previous_event = nil
91
+ @passed_reported = false
92
+ end
93
+
94
+ #: () -> ActivityTreeFilter
95
+ def filter
96
+ ActivityTreeFilter.new(@events, reported: @include_step, closing: @closing)
85
97
  end
86
98
 
87
99
  #: () -> ActivitySnapshotSequence
@@ -94,17 +106,30 @@ module PaperTrailDiff
94
106
  )
95
107
  end
96
108
 
97
- #: (ActivityEvent, RecordSnapshot?) -> void
98
- def consume(event, snapshot)
109
+ # A left-out event bounds nothing. A reported step it would have opened
110
+ # still moves the reported range's end past it, to the next boundary.
111
+ #: (ActivityEvent, RecordSnapshot?, bool) -> void
112
+ def consume(event, snapshot, kept)
99
113
  capture_first(snapshot)
100
- boundary = ActivityBoundary.from_version(event.version)
114
+ return pass(event) unless kept
115
+
116
+ boundary = ActivityBoundary.from_version(
117
+ event.version, recorded: @view.recorded_attributes(root: event.root?)
118
+ )
101
119
  @root_snapshots[version_key(event.version)] = snapshot if event.root?
102
120
  append_step(boundary, snapshot) if @previous_boundary
121
+ @selected_last_snapshot = snapshot if @passed_reported
122
+ @passed_reported = false
103
123
  @previous_boundary = boundary
104
124
  @previous_event = event
105
125
  @previous_snapshot = snapshot
106
126
  end
107
127
 
128
+ #: (ActivityEvent) -> void
129
+ def pass(event)
130
+ @passed_reported = true if !@include_step || @include_step.call(event)
131
+ end
132
+
108
133
  #: (RecordSnapshot?) -> void
109
134
  def capture_first(snapshot)
110
135
  return if @first_snapshot_seen
@@ -122,7 +147,7 @@ module PaperTrailDiff
122
147
 
123
148
  @steps << ActivityStep.between(
124
149
  from_boundary: previous_boundary, to_boundary: boundary,
125
- from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @snapshots
150
+ from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @view.retain?
126
151
  )
127
152
  @selected_last_snapshot = snapshot
128
153
  end
@@ -9,12 +9,13 @@ module PaperTrailDiff
9
9
 
10
10
  #: (untyped, untyped) -> void
11
11
  def initialize(start_boundary, end_boundary)
12
- @start_boundary = start_boundary
13
12
  @end_boundary = end_boundary
14
13
  @start_key = if Endpoint.version?(start_boundary)
15
14
  Support.chronological_version_key(start_boundary)
16
15
  end
17
16
  @start_time = Endpoint.version?(start_boundary) ? start_boundary.created_at : start_boundary
17
+ # A time has no transaction.
18
+ @opening_transaction = ActivityTransactionGroups.transaction_key(start_boundary)
18
19
  @end_time = Endpoint.version?(end_boundary) ? end_boundary.created_at : end_boundary
19
20
  @end_key = if Endpoint.version?(end_boundary)
20
21
  Support.chronological_version_key(end_boundary)
@@ -27,11 +28,16 @@ module PaperTrailDiff
27
28
  after_start?(version, key) && before_end?(version, key)
28
29
  end
29
30
 
30
- # Narrows an Active Record version relation by timestamp. Exact tie-breaking
31
- # remains in #include? so this works for integer, UUID, and custom version IDs.
31
+ # Narrows an Active Record version relation by timestamp, and to the
32
+ # start's transaction. Exact tie-breaking remains in #include? so this
33
+ # works for integer, UUID, and custom version IDs.
32
34
  #: (untyped) -> untyped
33
35
  def scope(relation)
34
- relation.where(created_at: @start_time..end_time)
36
+ in_time = relation.where(created_at: @start_time..end_time)
37
+ opening = @opening_transaction
38
+ return in_time unless opening
39
+
40
+ in_time.or(relation.where(transaction_id: opening.last))
35
41
  end
36
42
 
37
43
  #: () -> bool
@@ -39,16 +45,37 @@ module PaperTrailDiff
39
45
  !Endpoint.version?(@end_boundary)
40
46
  end
41
47
 
48
+ # Whether the state a version recorded after its change held inside the
49
+ # range. A range ending at a version ends at the state before it, so the
50
+ # change that version records is past the end, unlike #include?.
51
+ #: (untyped, untyped) -> bool
52
+ def recorded_before_end?(created_at, id)
53
+ end_key = @end_key
54
+ return created_at <= @end_boundary unless end_key
55
+
56
+ comparison = Support.version_key(created_at, id) <=> end_key
57
+ raise ConfigurationError, 'versions have incomparable timestamps' unless comparison
58
+
59
+ comparison.negative?
60
+ end
61
+
42
62
  private
43
63
 
44
- # @rbs @start_boundary: untyped
45
64
  # @rbs @end_boundary: untyped
46
65
  # @rbs @start_key: Array[untyped]?
47
66
  # @rbs @start_time: untyped
48
67
  # @rbs @end_key: Array[untyped]?
68
+ # @rbs @opening_transaction: Array[untyped]?
49
69
 
70
+ # A range starting at a version starts before that version's transaction,
71
+ # where PT-AT reads its associations. A version saved earlier in it, such
72
+ # as the child update behind a `touch: true` parent version, is a change
73
+ # inside the range.
50
74
  #: (untyped, Array[untyped]) -> bool
51
75
  def after_start?(version, key)
76
+ opening = @opening_transaction
77
+ return true if opening && ActivityTransactionGroups.transaction_key(version) == opening
78
+
52
79
  start_key = @start_key
53
80
  return key_before_or_equal?(start_key, key) if start_key
54
81
 
@@ -11,6 +11,7 @@ module PaperTrailDiff
11
11
  # @type var expected_ids: Array[untyped]
12
12
  expected = expected_ids.map { |id| id.to_s } # rubocop:disable Style/SymbolProc
13
13
  return false unless actual == expected
14
+ return false unless sti_member?(record, reflection, state)
14
15
  return true unless reflection.options[:as]
15
16
 
16
17
  type = event_attribute(record, reflection.type, state: state).to_s
@@ -27,6 +28,17 @@ module PaperTrailDiff
27
28
 
28
29
  private
29
30
 
31
+ #: (untyped, untyped, Symbol) -> bool
32
+ def sti_member?(record, reflection, state)
33
+ model_class = reflection.klass
34
+ return true if model_class.descends_from_active_record?
35
+
36
+ column = model_class.inheritance_column
37
+ type = event_attribute(record, column, state: state)
38
+ attributes = { column => type } #: Hash[untyped, untyped]
39
+ AssociationTraversal.sti_member?(model_class, attributes)
40
+ end
41
+
30
42
  #: (untyped, untyped, state: Symbol) -> Array[String]
31
43
  def relationship_owner_values(record, reflection, state:)
32
44
  Array(reflection.foreign_key).map do |key|
@@ -33,7 +33,7 @@ module PaperTrailDiff
33
33
  return [false, nil] unless previous && event.root?
34
34
 
35
35
  version = event.version
36
- model_class = Endpoint.model_class(version)
36
+ model_class = RecordedClass.for(version)
37
37
  return [false, nil] unless same_record?(previous, version)
38
38
 
39
39
  changes = @changeset.call(version, model_class)
@@ -108,9 +108,12 @@ module PaperTrailDiff
108
108
  end.uniq.sort.freeze
109
109
  end
110
110
 
111
+ # A polymorphic target's class is known only per record, so it cannot be
112
+ # checked here; a target that is not versioned raises when it is read.
111
113
  #: (untyped) -> bool
112
114
  def direct_versioned_reflection?(reflection)
113
- return false if reflection.polymorphic? || reflection.options[:through]
115
+ return true if reflection.polymorphic?
116
+ return false if reflection.options[:through]
114
117
  return false if reflection.macro == :has_and_belongs_to_many
115
118
 
116
119
  paper_trail = Object.const_get(:PaperTrail) #: untyped
@@ -2,24 +2,35 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Optional full/partial snapshot operations consumed by the activity sequence.
5
+ # Prepares the snapshot store for an activity build, one root at a time.
6
+ # Before that, it reads the live record a range closes on.
6
7
  class ActivitySnapshotProvider
7
- #: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
8
- def initialize(snapshotter:, refresher:, preparer:, activity_index: nil)
9
- @activity_index = activity_index
8
+ # `snapshotter` reads a full snapshot with a given history, and `refresher`
9
+ # builds the incremental refresher for one root's snapshots.
10
+ #: (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
11
+ def initialize(store:, snapshotter:, refresher:)
12
+ @store = store
10
13
  @snapshotter = snapshotter
11
14
  @refresher = refresher
12
- @preparer = preparer
13
15
  end
14
16
 
15
- #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
17
+ # Roots a batch prepared together share its history, so consecutive ones
18
+ # share these snapshots too, and the caches their refresher builds. They
19
+ # are the same for any root with that history, so reusing them depends on
20
+ # nothing but the history.
21
+ #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
16
22
  def prepare(
17
23
  record,
18
24
  root_versions,
19
25
  start_at: root_versions.first.created_at,
20
26
  end_at: root_versions.last.created_at
21
27
  )
22
- @preparer.call(record, root_versions, start_at: start_at, end_at: end_at)
28
+ history = @store.prepare(record, root_versions, start_at: start_at, end_at: end_at)
29
+ last = @last
30
+ return last if last && last.history.equal?(history)
31
+
32
+ @last = PreparedActivitySnapshots.new(history, store: @store, snapshotter: @snapshotter,
33
+ refresher: @refresher)
23
34
  end
24
35
 
25
36
  #: (untyped, untyped) -> RecordSnapshot?
@@ -27,44 +38,73 @@ module PaperTrailDiff
27
38
  @snapshotter.call(root_endpoint, context_endpoint)
28
39
  end
29
40
 
41
+ # @rbs @store: HistoricalSnapshotStore
42
+ # @rbs @snapshotter: untyped
43
+ # @rbs @refresher: untyped
44
+ # @rbs @last: PreparedActivitySnapshots?
45
+ end
46
+
47
+ # One root's full and incremental snapshots during an activity build. Each
48
+ # read passes along the history prepared for this root, so none depends on
49
+ # which root was prepared last.
50
+ class PreparedActivitySnapshots
51
+ attr_reader :history #: PreparedHistory?
52
+
53
+ #: (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
54
+ def initialize(history, store:, snapshotter:, refresher:)
55
+ @history = history
56
+ @store = store
57
+ @snapshotter = snapshotter
58
+ @refresher = refresher.call(self)
59
+ end
60
+
61
+ #: () -> PreparedActivityIndex?
62
+ def activity_index
63
+ @history&.activity_index
64
+ end
65
+
66
+ #: (untyped, untyped) -> RecordSnapshot?
67
+ def call(root_endpoint, context_endpoint)
68
+ @snapshotter.call(root_endpoint, context_endpoint, history: @history)
69
+ end
70
+
30
71
  #: (untyped, untyped, RecordSnapshot?, Array[String], event: ActivityEvent, isolated: bool) -> RecordSnapshot?
31
- def refresh( # rubocop:disable Metrics/ParameterLists
32
- root_endpoint,
33
- context_endpoint,
34
- previous_snapshot,
35
- branches,
36
- event:,
37
- isolated:
38
- )
39
- @refresher.call(
40
- root_endpoint,
41
- context_endpoint,
42
- previous_snapshot,
43
- branches,
44
- event: event,
45
- isolated: isolated
46
- )
72
+ def refresh(root_endpoint, context_endpoint, previous_snapshot, branches, event:, isolated:) # rubocop:disable Metrics/ParameterLists
73
+ @refresher.call(root_endpoint, context_endpoint, previous_snapshot, branches,
74
+ event: event, isolated: isolated)
47
75
  end
48
76
 
49
77
  #: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
50
78
  def advance_root(root_endpoint, context_endpoint, previous_snapshot, event:)
51
- @refresher.advance_root(
52
- root_endpoint,
53
- context_endpoint,
54
- previous_snapshot,
55
- event: event
56
- )
79
+ @refresher.advance_root(root_endpoint, context_endpoint, previous_snapshot, event: event)
57
80
  end
58
81
 
59
- #: () -> PreparedActivityIndex?
60
- def activity_index
61
- @activity_index&.call
82
+ # The branches a refresh rebuilds, with this root's history.
83
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
84
+ def custom(root_endpoint, context_endpoint, tree:, normalizer:)
85
+ @store.custom(root_endpoint, context_endpoint, tree: tree, normalizer: normalizer,
86
+ history: @history)
87
+ end
88
+
89
+ #: (untyped, habtm_version: untyped) -> untyped
90
+ def association_reader(context_version, habtm_version:)
91
+ @store.association_reader(context_version, habtm_version: habtm_version, history: @history)
92
+ end
93
+
94
+ #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
95
+ def record_transition(version)
96
+ @history&.record_transition(Endpoint.model_class(version), version.item_id, version)
97
+ end
98
+
99
+ #: (untyped, ?direct: bool) -> [bool, untyped]
100
+ def record_after(version, direct: false)
101
+ @history&.record_after(Endpoint.model_class(version), version.item_id, version,
102
+ direct: direct) || [false, nil]
62
103
  end
63
104
 
64
- # @rbs @activity_index: untyped
105
+ # @rbs @store: HistoricalSnapshotStore
65
106
  # @rbs @snapshotter: untyped
66
107
  # @rbs @refresher: untyped
67
- # @rbs @preparer: untyped
68
108
  end
69
109
 
70
110
  # Builds chronological snapshots, refreshing only branches affected by prior events.
@@ -116,7 +156,7 @@ module PaperTrailDiff
116
156
  incremental_root?(previous_event)
117
157
 
118
158
  branches = @transaction_groups.branches_for(previous_event)
119
- return full_snapshot(event) unless branches && @snapshotter.respond_to?(:refresh)
159
+ return full_snapshot(event) unless branches
120
160
 
121
161
  @snapshotter.refresh(
122
162
  root_endpoint(event.version),
@@ -130,8 +170,7 @@ module PaperTrailDiff
130
170
 
131
171
  #: (ActivityEvent) -> bool
132
172
  def incremental_root?(event)
133
- event.root? && @transaction_groups.isolated?(event) &&
134
- @snapshotter.respond_to?(:advance_root)
173
+ event.root? && @transaction_groups.isolated?(event)
135
174
  end
136
175
 
137
176
  #: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
@@ -0,0 +1,131 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Loads the `belongs_to` targets owners pointed at during one activity range:
6
+ # at its start and after each change inside it.
7
+ #
8
+ # PT-AT records a version's foreign keys as they stood after its change, so
9
+ # the target at the start comes from the latest version before it, and the
10
+ # version a range ends at names a target only after the range. Reading only
11
+ # the owners' versions inside the range misses a target whose owner did not
12
+ # change there -- an author renamed under an article nobody edited.
13
+ class ActivityTargetCandidateLoader
14
+ # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
15
+ # gem supports 3.1.
16
+ class Row
17
+ attr_reader :owner_id #: untyped
18
+ attr_reader :foreign_key_id #: untyped
19
+ attr_reader :foreign_type #: String?
20
+ attr_reader :created_at #: untyped
21
+ attr_reader :event #: String?
22
+ attr_reader :version_id #: untyped
23
+
24
+ #: (untyped, untyped, String?, ?untyped, ?String?, ?untyped) -> void
25
+ def initialize(owner_id, foreign_key_id, foreign_type, created_at = nil, event = nil, # rubocop:disable Metrics/ParameterLists
26
+ version_id = nil)
27
+ @owner_id = owner_id
28
+ @foreign_key_id = foreign_key_id
29
+ @foreign_type = foreign_type
30
+ @created_at = created_at
31
+ @event = event
32
+ @version_id = version_id
33
+ freeze
34
+ end
35
+ end
36
+
37
+ #: (untyped, Array[untyped], untyped, ActivityRange) -> void
38
+ def initialize(owner_class, owner_ids, reflection, range)
39
+ @owner_class = owner_class
40
+ @owner_ids = owner_ids
41
+ @reflection = reflection
42
+ @range = range
43
+ end
44
+
45
+ #: () -> Array[Row]
46
+ def call
47
+ rows = historical_rows.select do |row|
48
+ @range.recorded_before_end?(row.created_at, row.version_id)
49
+ end
50
+ @range.current_end? ? rows + current_rows : rows
51
+ end
52
+
53
+ # One shared query keeps the owner and timestamp needed to partition a
54
+ # batch's candidates back into each root's exact activity range.
55
+ #: () -> Array[Row]
56
+ def historical_rows
57
+ return [] if composite_foreign_key?
58
+
59
+ version_class = @owner_class.paper_trail.version_class
60
+ relation = candidate_scope(version_class).call(historical_relation(version_class))
61
+ historical_columns(relation, version_class).map do |row|
62
+ owner_id, id, type, created_at, event, version_id = row
63
+ Row.new(Support.record_id(@owner_class, owner_id), id, type, created_at, event, version_id)
64
+ end
65
+ end
66
+
67
+ # The live row holds the state at a range that ends at the current record.
68
+ #: () -> Array[Row]
69
+ def current_rows
70
+ return [] if composite_foreign_key? || @owner_class.composite_primary_key?
71
+
72
+ live_rows.filter_map do |owner_id, id, type|
73
+ Row.new(owner_id, id, type) unless id.nil?
74
+ end
75
+ end
76
+
77
+ private
78
+
79
+ # @rbs @owner_class: untyped
80
+ # @rbs @owner_ids: Array[untyped]
81
+ # @rbs @reflection: untyped
82
+ # @rbs @range: ActivityRange
83
+
84
+ #: (untyped) -> untyped
85
+ def historical_relation(version_class)
86
+ VersionTable.joined(association_class, version_class)
87
+ .where(foreign_key_name: @reflection.foreign_key)
88
+ .where(version_class.table_name => {
89
+ item_type: @owner_class.base_class.name, item_id: @owner_ids
90
+ })
91
+ end
92
+
93
+ #: (untyped, untyped) -> Array[Array[untyped]]
94
+ def historical_columns(relation, version_class)
95
+ versions = version_class.arel_table
96
+ associations = association_class.arel_table
97
+ relation.pluck(versions[:item_id], associations[:foreign_key_id],
98
+ associations[:foreign_type], versions[:created_at], versions[:event],
99
+ versions[:id])
100
+ end
101
+
102
+ # A polymorphic key names its target in a type column; any other names it
103
+ # in the reflection, so no type is read. Like the history, the live read
104
+ # takes owners of every class under the base class: a batch can ask for
105
+ # the owners of an association through one subclass.
106
+ #: () -> Array[Array[untyped]]
107
+ def live_rows
108
+ relation = @owner_class.base_class.unscoped.where(@owner_class.primary_key => @owner_ids)
109
+ key = @reflection.foreign_key
110
+ return relation.pluck(@owner_class.primary_key, key) unless @reflection.polymorphic?
111
+
112
+ relation.pluck(@owner_class.primary_key, key, @reflection.foreign_type)
113
+ end
114
+
115
+ #: (untyped) -> VersionAssociationCandidateScope
116
+ def candidate_scope(version_class)
117
+ VersionAssociationCandidateScope.new(version_class, @range.start_time,
118
+ end_at: @range.end_time)
119
+ end
120
+
121
+ #: () -> untyped
122
+ def association_class
123
+ @owner_class.paper_trail.version_association_class
124
+ end
125
+
126
+ #: () -> bool
127
+ def composite_foreign_key?
128
+ @reflection.foreign_key.is_a?(Array)
129
+ end
130
+ end
131
+ end