paper_trail_diff 0.16.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 +566 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -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 +3 -13
  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 +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -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 +74 -40
  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 +194 -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 +19 -5
  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 +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  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 +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
  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 +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  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 +41 -19
  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 +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  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 +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -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 +192 -91
  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 +37 -21
  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 +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  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 +0 -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 +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -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 +36 -2
  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 +121 -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 +15 -6
  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 +9 -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 +11 -5
  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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  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 +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
  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 +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  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 +27 -8
  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 +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  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 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +111 -52
  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 +15 -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 +13 -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 +28 -6
  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,75 +4,110 @@
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, ?record_transition: 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
15
  partial_snapshotter:,
15
- record_transition: nil
16
+ record_transition: nil,
17
+ root_state: nil
16
18
  )
17
- @tree = tree
19
+ @tree = traversal.tree
18
20
  @traversal = traversal
19
21
  @normalizer = normalizer
20
22
  @record_after = record_after
21
23
  @changeset = changeset
22
24
  @partial_snapshotter = partial_snapshotter
23
25
  @record_transition = record_transition
26
+ @root_state = root_state
24
27
  @unsupported_branches = {} #: Hash[String, Array[String]]
25
28
  @relationship_reflections = {} #: Hash[String, Array[untyped]]
26
29
  end
27
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`.
28
33
  #: (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [bool, RecordSnapshot?]
29
- def call( # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
30
- root_endpoint,
31
- context_endpoint,
32
- previous,
33
- event
34
- )
34
+ def call(root_endpoint, context_endpoint, previous, event)
35
35
  return [false, nil] unless previous && event.root?
36
36
 
37
- version = event.version
37
+ record, branches = target(previous, event.version, root_endpoint)
38
+ return [false, nil] unless record && branches
39
+
40
+ partial = nil #: RecordSnapshot?
41
+ unless branches.empty?
42
+ partial = @partial_snapshotter.call(root_endpoint, context_endpoint, branches)
43
+ return [false, nil] unless partial
44
+ end
45
+ [true, advanced(previous, record, partial)]
46
+ end
47
+
48
+ private
49
+
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
63
+
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))]
73
+ end
74
+
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)
38
85
  model_class = RecordedClass.for(version)
39
- return [false, nil] unless same_record?(previous, model_class, version)
86
+ return unless same_record?(previous, model_class, version)
40
87
 
41
88
  changed = changed_columns(version, model_class)
42
- return [false, nil] if changed.empty?
89
+ return if changed.empty?
43
90
 
44
91
  # A change of STI class can change the associations themselves.
45
92
  record = @record_after.call(version)
46
- return [false, nil] unless record && recorded_class(record) == model_class
93
+ return unless record && recorded_class(record) == model_class
47
94
 
48
- branches = branches_to_refresh(model_class, changed)
49
- partial = nil #: RecordSnapshot?
50
- unless branches.empty?
51
- partial = @partial_snapshotter.call(root_endpoint, context_endpoint, branches)
52
- end
53
- return [false, nil] if !branches.empty? && !partial
95
+ [record, branches_to_refresh(model_class, changed)]
96
+ end
54
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)
55
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
56
106
 
57
- incoming_associations = {} #: snapshot_associations
58
- incoming_associations = partial.associations if partial
59
- associations = previous.associations.merge(incoming_associations)
60
- return [true, previous] if attributes == previous.attributes &&
61
- associations == previous.associations
62
-
63
- [
64
- true,
65
- RecordSnapshot.new(
66
- type: previous.type,
67
- id: previous.id,
68
- attributes: attributes,
69
- associations: associations
70
- )
71
- ]
107
+ RecordSnapshot.new(type: previous.type, id: previous.id, attributes: attributes,
108
+ associations: associations)
72
109
  end
73
110
 
74
- private
75
-
76
111
  # @rbs @tree: AssociationTree
77
112
  # @rbs @traversal: AssociationTraversal
78
113
  # @rbs @normalizer: SnapshotNormalizer
@@ -80,6 +115,7 @@ module PaperTrailDiff
80
115
  # @rbs @changeset: untyped
81
116
  # @rbs @partial_snapshotter: untyped
82
117
  # @rbs @record_transition: untyped
118
+ # @rbs @root_state: untyped
83
119
  # @rbs @unsupported_branches: Hash[String, Array[String]]
84
120
  # @rbs @relationship_reflections: Hash[String, Array[untyped]]
85
121
 
@@ -95,9 +131,7 @@ module PaperTrailDiff
95
131
  return names unless transition
96
132
 
97
133
  before, after = transition
98
- names | (before.keys | after.keys).filter_map do |name|
99
- name.to_s unless before[name] == after[name]
100
- end
134
+ names | differing(before, after)
101
135
  end
102
136
 
103
137
  #: (untyped) -> untyped
@@ -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
@@ -6,17 +6,14 @@ module PaperTrailDiff
6
6
  class ActivitySnapshotDelta
7
7
  #: (before_attributes: Hash[untyped, untyped], after_attributes: Hash[untyped, untyped]) -> void
8
8
  def initialize(before_attributes:, after_attributes:)
9
- @before_attributes = normalize_hash(before_attributes)
10
- @after_attributes = normalize_hash(after_attributes)
9
+ @before_attributes = before_attributes.transform_keys(&:to_s)
10
+ @after_attributes = after_attributes.transform_keys(&:to_s)
11
11
  freeze
12
12
  end
13
13
 
14
14
  #: (RecordSnapshot) -> RecordSnapshot
15
15
  def apply(snapshot)
16
- attributes = snapshot.attributes.dup
17
- attributes.each_key do |name|
18
- attributes[name] = @after_attributes[name] if @after_attributes.key?(name)
19
- end
16
+ attributes = snapshot.attributes.merge(@after_attributes.slice(*snapshot.attributes.keys))
20
17
  return snapshot if attributes == snapshot.attributes
21
18
 
22
19
  RecordSnapshot.new(
@@ -37,11 +34,16 @@ module PaperTrailDiff
37
34
  @after_attributes[name.to_s]
38
35
  end
39
36
 
37
+ # Compared as text, so an id read as a string matches one read as an
38
+ # integer.
39
+ #: (untyped) -> bool
40
+ def changed?(name)
41
+ !before_value(name).to_s.eql?(after_value(name).to_s)
42
+ end
43
+
40
44
  #: (untyped) -> bool
41
45
  def relationship_changed?(reflection)
42
- relationship_keys(reflection).any? do |name|
43
- before_value(name).to_s != after_value(name).to_s
44
- end
46
+ relationship_keys(reflection).any? { |name| changed?(name) }
45
47
  end
46
48
 
47
49
  private
@@ -49,15 +51,10 @@ module PaperTrailDiff
49
51
  # @rbs @before_attributes: Hash[String, untyped]
50
52
  # @rbs @after_attributes: Hash[String, untyped]
51
53
 
52
- #: (Hash[untyped, untyped]) -> Hash[String, untyped]
53
- def normalize_hash(hash)
54
- hash.to_h { |name, value| [name.to_s, value] }.freeze
55
- end
56
-
57
54
  #: (untyped) -> Array[untyped]
58
55
  def relationship_keys(reflection)
59
56
  keys = Array(reflection.foreign_key)
60
- keys << reflection.type if reflection.options[:as]
57
+ keys << reflection.type if reflection.options.key?(:as)
61
58
  keys
62
59
  end
63
60
  end