paper_trail_diff 0.15.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -10,15 +10,21 @@ module PaperTrailDiff
10
10
  attr_reader :last_snapshot #: RecordSnapshot?
11
11
  attr_reader :last_boundary #: ActivityBoundary?
12
12
  attr_reader :last_event_snapshot #: RecordSnapshot?
13
+ # The event of `last_boundary`.
14
+ attr_reader :last_event #: ActivityEvent?
15
+ # What credits the rows of a step `last_boundary` opens.
16
+ attr_reader :last_attribution #: ChangeAttribution?
13
17
 
14
- #: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?) -> void
15
- def initialize(steps:, root_snapshots:, first_snapshot:, last_snapshot:, last_boundary: nil, last_event_snapshot: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
18
+ #: (steps: Array[ActivityStep], root_snapshots: Hash[Array[untyped], RecordSnapshot?], first_snapshot: RecordSnapshot?, last_snapshot: RecordSnapshot?, ?last_boundary: ActivityBoundary?, ?last_event_snapshot: RecordSnapshot?, ?last_event: ActivityEvent?, ?last_attribution: ChangeAttribution?) -> void
19
+ def initialize(steps:, root_snapshots:, first_snapshot:, last_snapshot:, last_boundary: nil, last_event_snapshot: nil, last_event: nil, last_attribution: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
16
20
  @steps = steps.freeze
17
21
  @root_snapshots = root_snapshots.freeze
18
22
  @first_snapshot = first_snapshot
19
23
  @last_snapshot = last_snapshot
20
24
  @last_boundary = last_boundary
21
25
  @last_event_snapshot = last_event_snapshot
26
+ @last_event = last_event
27
+ @last_attribution = last_attribution
22
28
  freeze
23
29
  end
24
30
 
@@ -33,9 +39,13 @@ module PaperTrailDiff
33
39
  # `closing` is the snapshot after the last event when the range closes on
34
40
  # the current record. Any other range ends at a root event, or at events
35
41
  # 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
42
+ # `include_step` says whether an event's step is reported. `root` names
43
+ # the root, whose steps then credit each change row to the version that
44
+ # made it (see ChangeAttribution).
45
+ #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, ?current: untyped, ?closing: RecordSnapshot?, ?root: RecordReference?) -> void
37
46
  def initialize( # rubocop:disable Metrics/ParameterLists
38
- root_versions, events, snapshotter, view:, current: nil, include_step: nil, closing: nil
47
+ root_versions, events, snapshotter,
48
+ view:, include_step:, current: nil, closing: nil, root: nil
39
49
  )
40
50
  @root_versions = root_versions
41
51
  @events = events
@@ -44,19 +54,26 @@ module PaperTrailDiff
44
54
  @current = current
45
55
  @include_step = include_step
46
56
  @closing = closing
57
+ @root = root
58
+ # A builder makes one pass; the rest of its state starts out nil.
59
+ @steps = []
60
+ @root_snapshots = {}
61
+ @transactions = {}
62
+ @first_pending = true
47
63
  end
48
64
 
49
65
  #: () -> ActivityHistory
50
66
  def call
51
- reset
52
67
  filter.call(sequence) { |event, snapshot, kept| consume(event, snapshot, kept) }
53
68
  ActivityHistory.new(
54
69
  steps: @steps,
55
70
  root_snapshots: @root_snapshots,
56
71
  first_snapshot: @first_snapshot,
57
- last_snapshot: final_snapshot,
72
+ last_snapshot: @selected_last_snapshot,
58
73
  last_boundary: @previous_boundary,
59
- last_event_snapshot: @previous_snapshot
74
+ last_event_snapshot: @previous_snapshot,
75
+ last_event: @previous_event,
76
+ last_attribution: @previous_attribution
60
77
  )
61
78
  end
62
79
 
@@ -72,24 +89,16 @@ module PaperTrailDiff
72
89
  # @rbs @steps: Array[ActivityStep]
73
90
  # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
74
91
  # @rbs @first_snapshot: RecordSnapshot?
92
+ # @rbs @first_pending: bool
75
93
  # @rbs @previous_snapshot: RecordSnapshot?
76
94
  # @rbs @selected_last_snapshot: RecordSnapshot?
77
95
  # @rbs @previous_boundary: ActivityBoundary?
78
96
  # @rbs @previous_event: ActivityEvent?
79
- # @rbs @passed_reported: bool
80
-
81
- #: () -> void
82
- def reset
83
- @steps = []
84
- @root_snapshots = {}
85
- @first_snapshot = nil
86
- @first_snapshot_seen = false
87
- @previous_snapshot = nil
88
- @selected_last_snapshot = nil
89
- @previous_boundary = nil
90
- @previous_event = nil
91
- @passed_reported = false
92
- end
97
+ # @rbs @previous_attribution: ChangeAttribution?
98
+ # @rbs @passed_reported: bool?
99
+ # @rbs @root: RecordReference?
100
+ # @rbs @transactions: Hash[Array[untyped], ChangeAttribution::Transaction]
101
+ # @rbs @opening: Array[Array[untyped]]?
93
102
 
94
103
  #: () -> ActivityTreeFilter
95
104
  def filter
@@ -108,63 +117,95 @@ module PaperTrailDiff
108
117
 
109
118
  # A left-out event bounds nothing. A reported step it would have opened
110
119
  # still moves the reported range's end past it, to the next boundary.
120
+ #
121
+ # The history starts at the first kept event whose step is reported. The
122
+ # events left out before it change nothing the root shows, unless they are
123
+ # of a transaction that crossed the window's start and has no event kept
124
+ # here: the snapshot at them is the state before that transaction, whose
125
+ # changes the window before this one reports (see ActivityTreeFilter). And
126
+ # a version filter starts it at the first change it keeps.
111
127
  #: (ActivityEvent, RecordSnapshot?, bool) -> void
112
128
  def consume(event, snapshot, kept)
113
- capture_first(snapshot)
114
129
  return pass(event) unless kept
115
130
 
131
+ capture_first(event, snapshot)
116
132
  boundary = ActivityBoundary.from_version(
117
- event.version, recorded: @view.recorded_attributes(root: event.root?)
133
+ event.version, recorded: @view.recorded_reader(root: event.root?)
118
134
  )
119
- @root_snapshots[version_key(event.version)] = snapshot if event.root?
135
+ @root_snapshots[Support.row_key(event.version)] = snapshot if event.root?
120
136
  append_step(boundary, snapshot) if @previous_boundary
121
137
  @selected_last_snapshot = snapshot if @passed_reported
122
138
  @passed_reported = false
123
139
  @previous_boundary = boundary
124
140
  @previous_event = event
125
141
  @previous_snapshot = snapshot
142
+ @previous_attribution = attribution(event, boundary)
143
+ end
144
+
145
+ # Inside a transaction a record's change can surface at a later event
146
+ # than its own, so the rows of a step its boundary opens are read with
147
+ # the boundaries its transaction kept before it (see ChangeAttribution).
148
+ #: (ActivityEvent, ActivityBoundary) -> ChangeAttribution?
149
+ def attribution(event, boundary)
150
+ root = @root
151
+ return unless root
152
+
153
+ transaction, complete = transaction_of(event)
154
+ attribution = ChangeAttribution.new(root: root, sources: [boundary], transaction: transaction,
155
+ complete: complete)
156
+ transaction.add(boundary)
157
+ attribution
158
+ end
159
+
160
+ # The boundaries kept so far of the event's transaction, and whether the
161
+ # history holds all of it. A version saved outside a transaction is a
162
+ # transaction of its own.
163
+ #: (ActivityEvent) -> [ChangeAttribution::Transaction, bool]
164
+ def transaction_of(event)
165
+ key = ActivityTransactionGroups.transaction_key(event.version)
166
+ return [ChangeAttribution::Transaction.new, true] unless key
167
+
168
+ [@transactions[key] ||= ChangeAttribution::Transaction.new, !opening.include?(key)]
169
+ end
170
+
171
+ # The transactions that began before the history did (see
172
+ # PreparedHistoryLoader#reload).
173
+ #: () -> Array[Array[untyped]]
174
+ def opening
175
+ @opening ||= @snapshotter.opening_transactions
126
176
  end
127
177
 
128
178
  #: (ActivityEvent) -> void
129
179
  def pass(event)
130
- @passed_reported = true if !@include_step || @include_step.call(event)
180
+ @passed_reported = true if reported?(event)
131
181
  end
132
182
 
133
- #: (RecordSnapshot?) -> void
134
- def capture_first(snapshot)
135
- return if @first_snapshot_seen
183
+ #: (ActivityEvent, RecordSnapshot?) -> void
184
+ def capture_first(event, snapshot)
185
+ return unless @first_pending && reported?(event)
136
186
 
137
187
  @first_snapshot = snapshot
138
- @first_snapshot_seen = true
188
+ @first_pending = false
189
+ end
190
+
191
+ #: (ActivityEvent) -> bool
192
+ def reported?(event)
193
+ @include_step.call(event)
139
194
  end
140
195
 
196
+ # The step from the previous boundary, which `consume` has, to this one.
141
197
  #: (ActivityBoundary, RecordSnapshot?) -> void
142
198
  def append_step(boundary, snapshot)
143
- return unless include_previous_step?
144
-
145
- previous_boundary = @previous_boundary
146
- return unless previous_boundary
199
+ previous_boundary = @previous_boundary #: ActivityBoundary
200
+ previous_event = @previous_event #: ActivityEvent
201
+ return unless reported?(previous_event)
147
202
 
148
203
  @steps << ActivityStep.between(
149
204
  from_boundary: previous_boundary, to_boundary: boundary,
150
- from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @view.retain?
205
+ from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @view.retain?,
206
+ attribution: @previous_attribution
151
207
  )
152
208
  @selected_last_snapshot = snapshot
153
209
  end
154
-
155
- #: () -> bool
156
- def include_previous_step?
157
- !@include_step || @include_step.call(@previous_event)
158
- end
159
-
160
- #: () -> RecordSnapshot?
161
- def final_snapshot
162
- @include_step ? @selected_last_snapshot : @previous_snapshot
163
- end
164
-
165
- #: (untyped) -> Array[untyped]
166
- def version_key(version)
167
- [version.class.name, version.id]
168
- end
169
210
  end
170
211
  end
@@ -5,7 +5,6 @@ module PaperTrailDiff
5
5
  # Tests activity versions against a historical-version or wall-clock range end.
6
6
  class ActivityRange
7
7
  attr_reader :start_time #: untyped
8
- attr_reader :end_time #: untyped
9
8
 
10
9
  #: (untyped, untyped) -> void
11
10
  def initialize(start_boundary, end_boundary)
@@ -16,7 +15,6 @@ module PaperTrailDiff
16
15
  @start_time = Endpoint.version?(start_boundary) ? start_boundary.created_at : start_boundary
17
16
  # A time has no transaction.
18
17
  @opening_transaction = ActivityTransactionGroups.transaction_key(start_boundary)
19
- @end_time = Endpoint.version?(end_boundary) ? end_boundary.created_at : end_boundary
20
18
  @end_key = if Endpoint.version?(end_boundary)
21
19
  Support.chronological_version_key(end_boundary)
22
20
  end
@@ -28,35 +26,16 @@ module PaperTrailDiff
28
26
  after_start?(version, key) && before_end?(version, key)
29
27
  end
30
28
 
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.
34
- #: (untyped) -> untyped
35
- def scope(relation)
36
- in_time = relation.where(created_at: @start_time..end_time)
29
+ # A range starting at a version starts before that version's transaction,
30
+ # where PT-AT reads its associations. A version saved earlier in it, such
31
+ # as the child update behind a `touch: true` parent version, is a change
32
+ # inside the range.
33
+ #: (untyped) -> bool
34
+ def opening?(version)
37
35
  opening = @opening_transaction
38
- return in_time unless opening
39
-
40
- in_time.or(relation.where(transaction_id: opening.last))
41
- end
42
-
43
- #: () -> bool
44
- def current_end?
45
- !Endpoint.version?(@end_boundary)
46
- end
36
+ return false unless opening
47
37
 
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?
38
+ ActivityTransactionGroups.transaction_key(version) == opening
60
39
  end
61
40
 
62
41
  private
@@ -67,14 +46,9 @@ module PaperTrailDiff
67
46
  # @rbs @end_key: Array[untyped]?
68
47
  # @rbs @opening_transaction: Array[untyped]?
69
48
 
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.
74
49
  #: (untyped, Array[untyped]) -> bool
75
50
  def after_start?(version, key)
76
- opening = @opening_transaction
77
- return true if opening && ActivityTransactionGroups.transaction_key(version) == opening
51
+ return true if opening?(version)
78
52
 
79
53
  start_key = @start_key
80
54
  return key_before_or_equal?(start_key, key) if start_key
@@ -4,70 +4,109 @@
4
4
  module PaperTrailDiff
5
5
  # Advances scalar-only root events while retaining already reconstructed associations.
6
6
  class ActivityRootSnapshotRefresher
7
- #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
7
+ # `root_state` gives the state a root endpoint's snapshot is built from,
8
+ # where prepared history builds it.
9
+ #: (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped, ?root_state: untyped) -> void
8
10
  def initialize( # rubocop:disable Metrics/ParameterLists
9
- tree:,
10
11
  traversal:,
11
12
  normalizer:,
12
13
  record_after:,
13
14
  changeset:,
14
- partial_snapshotter:
15
+ partial_snapshotter:,
16
+ record_transition: nil,
17
+ root_state: nil
15
18
  )
16
- @tree = tree
19
+ @tree = traversal.tree
17
20
  @traversal = traversal
18
21
  @normalizer = normalizer
19
22
  @record_after = record_after
20
23
  @changeset = changeset
21
24
  @partial_snapshotter = partial_snapshotter
25
+ @record_transition = record_transition
26
+ @root_state = root_state
22
27
  @unsupported_branches = {} #: Hash[String, Array[String]]
23
28
  @relationship_reflections = {} #: Hash[String, Array[untyped]]
24
29
  end
25
30
 
31
+ # `previous` is the snapshot at the root's `event`, and the result the one
32
+ # at the next event, whose root is read at `root_endpoint`.
26
33
  #: (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [bool, RecordSnapshot?]
27
- def call( # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
28
- root_endpoint,
29
- context_endpoint,
30
- previous,
31
- event
32
- )
34
+ def call(root_endpoint, context_endpoint, previous, event)
33
35
  return [false, nil] unless previous && event.root?
34
36
 
35
- version = event.version
36
- model_class = RecordedClass.for(version)
37
- return [false, nil] unless same_record?(previous, version)
38
-
39
- changes = @changeset.call(version, model_class)
40
- return [false, nil] unless changes.respond_to?(:each)
41
- return [false, nil] if changes.empty?
37
+ record, branches = target(previous, event.version, root_endpoint)
38
+ return [false, nil] unless record && branches
42
39
 
43
- branches = branches_to_refresh(model_class, changes)
44
40
  partial = nil #: RecordSnapshot?
45
41
  unless branches.empty?
46
42
  partial = @partial_snapshotter.call(root_endpoint, context_endpoint, branches)
43
+ return [false, nil] unless partial
47
44
  end
48
- return [false, nil] if !branches.empty? && !partial
45
+ [true, advanced(previous, record, partial)]
46
+ end
49
47
 
50
- attributes = advanced_attributes(previous, version, changes)
51
- return [false, nil] unless attributes
48
+ private
52
49
 
53
- incoming_associations = {} #: snapshot_associations
54
- incoming_associations = partial.associations if partial
55
- associations = previous.associations.merge(incoming_associations)
56
- return [true, previous] if attributes == previous.attributes &&
57
- associations == previous.associations
50
+ # The snapshot at a root version starts from the state stored in that
51
+ # version, and the next one from the state at its own root endpoint. Where
52
+ # prepared history built both from those states, the two are compared
53
+ # directly; nothing else needs to be decoded. Otherwise the version's
54
+ # recorded change and the record after it are read.
55
+ #: (RecordSnapshot, untyped, untyped) -> [untyped, Array[String]]?
56
+ def target(previous, version, root_endpoint)
57
+ before = @root_state&.call(version)
58
+ after = before && @root_state&.call(root_endpoint)
59
+ return advance_target(previous, version) unless before && after
60
+
61
+ state_target(previous, version, before, after)
62
+ end
58
63
 
59
- [
60
- true,
61
- RecordSnapshot.new(
62
- type: previous.type,
63
- id: previous.id,
64
- attributes: attributes,
65
- associations: associations
66
- )
67
- ]
64
+ # The state at the next event and the branches whose reads the root's
65
+ # change between the two states can alter. A change of STI class can
66
+ # change the associations themselves, so it is rebuilt in full.
67
+ #: (RecordSnapshot, untyped, PreparedRecordState, PreparedRecordState) -> [PreparedRecordState, Array[String]]?
68
+ def state_target(previous, version, before, after)
69
+ model_class = before.model_class
70
+ return unless after.model_class == model_class && same_record?(previous, model_class, version)
71
+
72
+ [after, branches_to_refresh(model_class, differing(before.attributes, after.attributes))]
68
73
  end
69
74
 
70
- private
75
+ # The names of the columns whose values differ between two sets of them.
76
+ #: (Hash[untyped, untyped], Hash[untyped, untyped]) -> Array[String]
77
+ def differing(old, new)
78
+ (old.keys | new.keys).filter_map { |name| name.to_s unless old[name] == new[name] }
79
+ end
80
+
81
+ # The record after a root version and the branches its change reaches, or
82
+ # nil when the version cannot be applied to the previous snapshot alone.
83
+ #: (RecordSnapshot, untyped) -> [untyped, Array[String]]?
84
+ def advance_target(previous, version)
85
+ model_class = RecordedClass.for(version)
86
+ return unless same_record?(previous, model_class, version)
87
+
88
+ changed = changed_columns(version, model_class)
89
+ return if changed.empty?
90
+
91
+ # A change of STI class can change the associations themselves.
92
+ record = @record_after.call(version)
93
+ return unless record && recorded_class(record) == model_class
94
+
95
+ [record, branches_to_refresh(model_class, changed)]
96
+ end
97
+
98
+ # The previous snapshot with the record's attributes and any branches read
99
+ # again, or the previous snapshot itself when nothing differs.
100
+ #: (RecordSnapshot, untyped, RecordSnapshot?) -> RecordSnapshot
101
+ def advanced(previous, record, partial)
102
+ attributes = @normalizer.attributes_for(record, tree: @tree, path: '')
103
+ associations = previous.associations
104
+ associations = associations.merge(partial.associations) if partial
105
+ return previous if attributes == previous.attributes && associations == previous.associations
106
+
107
+ RecordSnapshot.new(type: previous.type, id: previous.id, attributes: attributes,
108
+ associations: associations)
109
+ end
71
110
 
72
111
  # @rbs @tree: AssociationTree
73
112
  # @rbs @traversal: AssociationTraversal
@@ -75,22 +114,34 @@ module PaperTrailDiff
75
114
  # @rbs @record_after: untyped
76
115
  # @rbs @changeset: untyped
77
116
  # @rbs @partial_snapshotter: untyped
117
+ # @rbs @record_transition: untyped
118
+ # @rbs @root_state: untyped
78
119
  # @rbs @unsupported_branches: Hash[String, Array[String]]
79
120
  # @rbs @relationship_reflections: Hash[String, Array[untyped]]
80
121
 
81
- #: (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
82
- def advanced_attributes(previous, version, changes)
83
- return previous.attributes if changes.empty?
122
+ # The columns the version changed, from its changeset and from the states
123
+ # either side of it. The changeset leaves out columns that `only:` or
124
+ # `ignore:` exclude and keys written without a version, which the states
125
+ # hold.
126
+ #: (untyped, untyped) -> Array[String]
127
+ def changed_columns(version, model_class)
128
+ changes = @changeset.call(version, model_class)
129
+ names = changes.respond_to?(:each_key) ? changes.each_key.map(&:to_s) : [] #: Array[String]
130
+ transition = @record_transition&.call(version)
131
+ return names unless transition
84
132
 
85
- record = @record_after.call(version)
86
- return unless record
133
+ before, after = transition
134
+ names | differing(before, after)
135
+ end
87
136
 
88
- @normalizer.attributes_for(record, tree: @tree, path: '')
137
+ #: (untyped) -> untyped
138
+ def recorded_class(record)
139
+ record.is_a?(PreparedRecordState) ? record.model_class : record.class
89
140
  end
90
141
 
91
- #: (untyped, untyped) -> Array[String]
92
- def branches_to_refresh(model_class, changes)
93
- (unsupported_branches(model_class) + changed_relationship_branches(model_class, changes))
142
+ #: (untyped, Array[String]) -> Array[String]
143
+ def branches_to_refresh(model_class, changed)
144
+ (unsupported_branches(model_class) + changed_relationship_branches(model_class, changed))
94
145
  .uniq
95
146
  .sort
96
147
  .freeze
@@ -122,15 +173,16 @@ module PaperTrailDiff
122
173
  false
123
174
  end
124
175
 
125
- #: (RecordSnapshot, untyped) -> bool
126
- def same_record?(snapshot, version)
127
- identity = Endpoint.identity(version)
128
- snapshot.type.to_s == identity.fetch(0) && snapshot.id.to_s == identity.fetch(1)
176
+ # The snapshot names the record's class, which for an STI subclass is not
177
+ # the base class the version names.
178
+ #: (RecordSnapshot, untyped, untyped) -> bool
179
+ def same_record?(snapshot, model_class, version)
180
+ snapshot.type.to_s == model_class.name.to_s &&
181
+ snapshot.id.to_s == Endpoint.identity(version).fetch(1)
129
182
  end
130
183
 
131
- #: (untyped, untyped) -> Array[String]
132
- def changed_relationship_branches(model_class, changes)
133
- changed = changes.each_key.map(&:to_s)
184
+ #: (untyped, Array[String]) -> Array[String]
185
+ def changed_relationship_branches(model_class, changed)
134
186
  root_relationship_reflections(model_class).filter_map do |reflection|
135
187
  reflection.name.to_s if changed.intersect?(relationship_columns(reflection))
136
188
  end
@@ -5,19 +5,20 @@ module PaperTrailDiff
5
5
  # Root checkpoint steps recovered from the snapshots an activity pass retained,
6
6
  # so a combined result does not reconstruct the same boundaries twice.
7
7
  module ActivityRootSteps
8
- module_function
9
-
10
8
  # A window closing on current state ends at the live record, which no
11
- # version-keyed snapshot can supply, so that endpoint is passed in.
9
+ # version-keyed snapshot can supply, so that endpoint is passed in. A plan
10
+ # that replays versions a filter left out reports the steps of the ones it
11
+ # kept, as `timeline` does. Every version a plan names is a root event of
12
+ # the history, which keeps its snapshot.
12
13
  #: (RootVersionPlan, Hash[Array[untyped], RecordSnapshot?], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Array[Step]
13
- def call(plan, root_snapshots, closing_snapshot: nil, captured_at: nil)
14
- plan.steps.map do |from_endpoint, to_endpoint|
14
+ def self.call(plan, root_snapshots, closing_snapshot: nil, captured_at: nil)
15
+ plan.steps.select { |from, _to| plan.mutation?(from) }.map do |from_endpoint, to_endpoint|
15
16
  Step.new(
16
17
  from_version: from_endpoint,
17
18
  to_version: to_endpoint,
18
19
  captured_at: captured_at,
19
20
  diff: Engine.compare(
20
- root_snapshots[version_key(from_endpoint)],
21
+ root_snapshots.fetch(Support.row_key(from_endpoint)),
21
22
  snapshot_for(to_endpoint, root_snapshots, closing_snapshot)
22
23
  )
23
24
  )
@@ -25,15 +26,11 @@ module PaperTrailDiff
25
26
  end
26
27
 
27
28
  #: (untyped, Hash[Array[untyped], RecordSnapshot?], RecordSnapshot?) -> RecordSnapshot?
28
- def snapshot_for(endpoint, root_snapshots, closing_snapshot)
29
+ def self.snapshot_for(endpoint, root_snapshots, closing_snapshot)
29
30
  return closing_snapshot if Endpoint.record?(endpoint)
30
31
 
31
- root_snapshots[version_key(endpoint)]
32
- end
33
-
34
- #: (untyped) -> Array[untyped]
35
- def version_key(version)
36
- [version.class.name, version.id]
32
+ root_snapshots.fetch(Support.row_key(endpoint))
37
33
  end
34
+ private_class_method :snapshot_for
38
35
  end
39
36
  end
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Which events a `version_scope:` reports in activity on associations.
6
+ #
7
+ # PT-AT reads a transaction's records as they stood before it began, so the
8
+ # changes a transaction saved surface together in its last step rather than
9
+ # each in the step of its own version (see ActivityTransactionGrouper). No
10
+ # step inside a transaction can be credited to one version of it, and
11
+ # leaving one out would lose the changes it carried. A transaction is
12
+ # therefore reported whole when the filter keeps any version saved in it, of
13
+ # whichever record, and a version saved outside a transaction when the
14
+ # filter keeps that version. Both are answered from the version tables, so
15
+ # every window and every way of asking reads the same transaction alike.
16
+ #
17
+ # One filter serves a request. It reads the answers for each history once,
18
+ # in one statement per version table and 500 transactions or versions, and
19
+ # the roots a batch prepared together share them.
20
+ class ActivityScopeFilter
21
+ #: (untyped) -> void
22
+ def initialize(scope)
23
+ @scope = scope
24
+ @transactions = {} #: Hash[Array[untyped], bool]
25
+ @versions = {} #: Hash[Array[untyped], bool]
26
+ @histories = Set.new #: Set[PreparedHistory]
27
+ end
28
+
29
+ # Reads the answers for every version `history` holds, once for each
30
+ # history, and for those of `versions` it does not hold.
31
+ #: (PreparedHistory?, Array[untyped]) -> void
32
+ def prepare(history, versions)
33
+ read(history.versions) if history && @histories.add?(history)
34
+ read(versions)
35
+ end
36
+
37
+ # Whether the filter keeps a version of `version`'s transaction, or
38
+ # `version` itself when it was saved outside one. `prepare` reads it first.
39
+ #: (untyped) -> bool
40
+ def kept?(version)
41
+ transaction = ActivityTransactionGroups.transaction_key(version)
42
+ return @transactions.fetch(transaction) if transaction
43
+
44
+ @versions.fetch(Support.row_key(version))
45
+ end
46
+
47
+ private
48
+
49
+ # @rbs @scope: untyped
50
+ # @rbs @transactions: Hash[Array[untyped], bool]
51
+ # @rbs @versions: Hash[Array[untyped], bool]
52
+ # @rbs @histories: Set[PreparedHistory]
53
+
54
+ #: (Array[untyped]) -> void
55
+ def read(versions)
56
+ versions.group_by(&:class).each do |version_class, group|
57
+ name = version_class.name
58
+ saved = group.group_by { |version| VersionBoundary.transaction_id(version) }
59
+ loose = saved.delete(nil) || []
60
+ read_kept(version_class, @transactions, name, saved.keys, :transaction_id)
61
+ read_kept(version_class, @versions, name, loose.map(&:id), :id)
62
+ end
63
+ end
64
+
65
+ # Records which of the distinct `values` of `column` the filter keeps
66
+ # versions with.
67
+ #: (untyped, Hash[Array[untyped], bool], String, Array[untyped], Symbol) -> void
68
+ def read_kept(version_class, answers, name, values, column)
69
+ values.reject { |value| answers.key?([name, value]) }
70
+ .each_slice(Support::IDS_PER_STATEMENT) do |slice|
71
+ kept = @scope.call(version_class.where(column => slice)).pluck(column)
72
+ slice.each { |value| answers[[name, value]] = false }
73
+ kept.each { |value| answers[[name, value]] = true }
74
+ end
75
+ end
76
+ end
77
+ end