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
@@ -3,12 +3,13 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Selects each root's versions for a batched range in a fixed number of
6
- # queries. Only the range forms that mean the same thing for every root are
7
- # supported: a shared wall-clock window, or each root's own whole history.
6
+ # queries per 500 roots. Only the range forms that mean the same thing for
7
+ # every root are supported: a shared wall-clock window, or each root's own
8
+ # whole history.
8
9
  class BatchedRootVersions
9
- #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
10
+ #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, whole: bool, windows: Hash[Array[String], TimeRange]) -> void
10
11
  def initialize( # rubocop:disable Metrics/ParameterLists
11
- records, time_range:, version_scope:, live_endpoints:, context_required:, windows:
12
+ records, time_range:, version_scope:, live_endpoints:, context_required:, whole:, windows:
12
13
  )
13
14
  @records = records
14
15
  # Roots whose window moved to a transaction's start, by identity.
@@ -16,6 +17,9 @@ module PaperTrailDiff
16
17
  # An activity view needs a root to reconstruct from even in a window with
17
18
  # no root version, exactly as a single-record activity timeline does.
18
19
  @context_required = context_required
20
+ # Activity on associations replays every version a filter leaves out
21
+ # (see RootVersionSelection), whether or not the root takes a context.
22
+ @whole = whole
19
23
  @time_range = time_range
20
24
  @version_scope = version_scope
21
25
  @live_endpoints = live_endpoints
@@ -38,20 +42,23 @@ module PaperTrailDiff
38
42
  # @rbs @version_scope: untyped
39
43
  # @rbs @live_endpoints: Hash[Array[String], untyped]?
40
44
  # @rbs @context_required: bool
45
+ # @rbs @whole: bool
41
46
  # @rbs @windows: Hash[Array[String], TimeRange]
42
47
 
48
+ # Each statement reads the versions of 500 roots.
43
49
  #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
44
50
  def select_model(model_class, records, selected)
45
- in_range, chosen, trailing = model_versions(model_class, records)
46
- records.each do |record|
47
- key = Endpoint.identity(record)
48
- own = own_window(key, record.id.to_s, in_range, trailing)
49
- selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
51
+ records.each_slice(Support::IDS_PER_STATEMENT) do |slice|
52
+ in_range, chosen, trailing = model_versions(model_class, slice)
53
+ slice.each do |record|
54
+ key = Endpoint.identity(record)
55
+ own = own_window(key, record.id.to_s, in_range, trailing)
56
+ selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
57
+ end
50
58
  end
51
59
  end
52
60
 
53
- # Moved windows only start and end earlier, so the versions read for the
54
- # widest of them hold each root's own, and the first left past a moved end.
61
+ # Each root's own versions, and the first after its window (see OwnWindow).
55
62
  #: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
56
63
  def own_window(key, id, in_range, trailing)
57
64
  loaded = in_range.fetch(id, [])
@@ -59,8 +66,8 @@ module PaperTrailDiff
59
66
 
60
67
  # A batch moves windows only when it has one, so this is never nil.
61
68
  window = @windows.fetch(key) { @time_range } #: untyped
62
- own, rest = loaded.partition { |version| window.include?(version.created_at) }
63
- [own, rest.find { |version| version.created_at >= window.end_time } || trailing[id]]
69
+ own, past = OwnWindow.split(window, loaded)
70
+ [own, past || trailing[id]]
64
71
  end
65
72
 
66
73
  #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
@@ -80,9 +87,7 @@ module PaperTrailDiff
80
87
  range = @time_range
81
88
  return unless range
82
89
 
83
- moved = records.filter_map { |record| @windows[Endpoint.identity(record)]&.begin_time }
84
- start = [range.begin_time, *moved].min
85
- TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
90
+ OwnWindow.widest(range, records.filter_map { |record| @windows[Endpoint.identity(record)] })
86
91
  end
87
92
 
88
93
  #: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
@@ -93,8 +98,8 @@ module PaperTrailDiff
93
98
  after_range: after_range,
94
99
  windowed: !@time_range.nil?,
95
100
  context_required: @context_required,
96
- filtered: !@version_scope.nil?,
97
- live_endpoint: live_endpoint
101
+ live_endpoint: live_endpoint,
102
+ whole: @whole
98
103
  ).call
99
104
  end
100
105
 
@@ -116,10 +121,10 @@ module PaperTrailDiff
116
121
  VersionScopeFilter.new(@version_scope).chosen_ids(range_scope(model_class, records, range))
117
122
  end
118
123
 
124
+ # RootVersionSelection puts each root's versions in order.
119
125
  #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
120
126
  def grouped_versions(model_class, records, range)
121
- VersionQuery.chronological(range_scope(model_class, records, range))
122
- .group_by { |version| version.item_id.to_s }
127
+ range_scope(model_class, records, range).group_by { |version| version.item_id.to_s }
123
128
  end
124
129
 
125
130
  #: (untyped, Array[untyped], TimeRange?) -> untyped
@@ -4,9 +4,8 @@
4
4
  module PaperTrailDiff
5
5
  # Reconstructs selected root branches and merges them into a prior immutable snapshot.
6
6
  class BranchSnapshotRefresher
7
- #: (tree: AssociationTree, ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped) -> void
7
+ #: (ignore_policy: IgnorePolicy, traversal: AssociationTraversal, pool: SnapshotPool, normalizer: SnapshotNormalizer, full_snapshotter: untyped, partial_snapshotter: untyped, association_reader: untyped, record_transition: untyped, ?prepared_record_after: untyped, ?root_state: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
9
- tree:,
10
9
  ignore_policy:,
11
10
  traversal:,
12
11
  pool:,
@@ -15,9 +14,10 @@ module PaperTrailDiff
15
14
  partial_snapshotter:,
16
15
  association_reader:,
17
16
  record_transition:,
18
- prepared_record_after: nil
17
+ prepared_record_after: nil,
18
+ root_state: nil
19
19
  )
20
- @tree = tree
20
+ @tree = traversal.tree
21
21
  @ignore_policy = ignore_policy
22
22
  @traversal = traversal
23
23
  @pool = pool
@@ -32,15 +32,23 @@ module PaperTrailDiff
32
32
  prepared_record_after: prepared_record_after
33
33
  )
34
34
  @root_refresher = ActivityRootSnapshotRefresher.new(
35
- tree: tree, traversal: traversal, normalizer: normalizer,
35
+ traversal: traversal, normalizer: normalizer,
36
36
  record_after: @event_refresher.method(:record_after),
37
37
  changeset: @event_refresher.method(:deserialized_changeset),
38
- partial_snapshotter: method(:partial_snapshot)
38
+ partial_snapshotter: method(:partial_snapshot),
39
+ record_transition: record_transition,
40
+ root_state: root_state
39
41
  )
40
42
  end
41
43
 
44
+ # Without associations there is no prepared history, so nothing but the
45
+ # version's own record could say what it left, and that misses a change
46
+ # saved after it without a version. A full snapshot reads the next
47
+ # recorded state instead, and with no branches to carry it costs no more.
42
48
  #: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
43
49
  def advance_root(root_endpoint, context_endpoint, previous_snapshot, event:)
50
+ return full_snapshot(root_endpoint, context_endpoint) if @tree.empty?
51
+
44
52
  handled, incremental = @root_refresher.call(
45
53
  root_endpoint,
46
54
  context_endpoint,
@@ -53,7 +61,7 @@ module PaperTrailDiff
53
61
  end
54
62
 
55
63
  #: (untyped, untyped, RecordSnapshot?, Array[String], ?event: ActivityEvent?, ?isolated: bool) -> RecordSnapshot?
56
- def call( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
64
+ def call( # rubocop:disable Metrics/ParameterLists
57
65
  root_endpoint,
58
66
  context_endpoint,
59
67
  previous_snapshot,
@@ -62,30 +70,19 @@ module PaperTrailDiff
62
70
  isolated: false
63
71
  )
64
72
  return full_snapshot(root_endpoint, context_endpoint) unless previous_snapshot
73
+
74
+ branches = with_habtm(root_endpoint, context_endpoint, branches)
65
75
  if isolated && event && branches.length > 1
66
- return refresh_independent_branches(
67
- root_endpoint,
68
- context_endpoint,
69
- previous_snapshot,
70
- branches,
71
- event
72
- )
76
+ return refresh_independent_branches(root_endpoint, context_endpoint, previous_snapshot,
77
+ branches, event)
73
78
  end
74
79
 
75
- endpoints = [root_endpoint, context_endpoint]
76
- handled, incremental = incremental_event(
77
- endpoints,
78
- previous_snapshot,
79
- branches,
80
- event,
81
- isolated
82
- )
83
- return incremental if handled
84
-
85
- partial = partial_snapshot(root_endpoint, context_endpoint, branches)
86
- return full_snapshot(root_endpoint, context_endpoint) unless partial
87
-
88
- merge(previous_snapshot, partial)
80
+ if isolated
81
+ handled, incremental = @event_refresher.call(root_endpoint, context_endpoint,
82
+ previous_snapshot, branches, event)
83
+ return incremental if handled
84
+ end
85
+ refreshed(root_endpoint, context_endpoint, previous_snapshot, branches)
89
86
  end
90
87
 
91
88
  private
@@ -100,17 +97,14 @@ module PaperTrailDiff
100
97
  # @rbs @event_refresher: ActivityEventSnapshotRefresher
101
98
  # @rbs @root_refresher: ActivityRootSnapshotRefresher
102
99
 
103
- #: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
104
- def incremental_event(endpoints, previous, branches, event, isolated)
105
- return [false, nil] unless isolated
106
-
107
- @event_refresher.call(
108
- endpoints.fetch(0),
109
- endpoints.fetch(1),
110
- previous,
111
- branches,
112
- event
113
- )
100
+ # A root version's HABTM members include any created earlier in its
101
+ # transaction. A range ending at that version leaves those creations out
102
+ # as events, so the branch is read again there, whatever event led to it.
103
+ #: (untyped, untyped, Array[String]) -> Array[String]
104
+ def with_habtm(root_endpoint, context_endpoint, branches)
105
+ root = Endpoint.version?(root_endpoint) &&
106
+ VersionBoundary.same_version?(root_endpoint, context_endpoint)
107
+ root ? branches | @traversal.habtm_paths(RecordedClass.for(root_endpoint)) : branches
114
108
  end
115
109
 
116
110
  #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
@@ -139,10 +133,15 @@ module PaperTrailDiff
139
133
  end
140
134
  return snapshot if remaining.empty?
141
135
 
142
- partial = partial_snapshot(root_endpoint, context_endpoint, remaining)
143
- return full_snapshot(root_endpoint, context_endpoint) unless partial
136
+ refreshed(root_endpoint, context_endpoint, snapshot, remaining)
137
+ end
144
138
 
145
- merge(snapshot, partial)
139
+ # The snapshot with these branches read again from history, or a full
140
+ # snapshot when they cannot be read alone.
141
+ #: (untyped, untyped, RecordSnapshot, Array[String]) -> RecordSnapshot?
142
+ def refreshed(root_endpoint, context_endpoint, snapshot, branches)
143
+ partial = partial_snapshot(root_endpoint, context_endpoint, branches)
144
+ partial ? merge(snapshot, partial) : full_snapshot(root_endpoint, context_endpoint)
146
145
  end
147
146
 
148
147
  #: (untyped, untyped, Array[String]) -> RecordSnapshot?
@@ -0,0 +1,314 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Credits each change row to the version that made its change, which need
6
+ # not be its step's source: a transaction group starts at one record's
7
+ # event, and inside a transaction a record's change can surface at a later
8
+ # event than its own (see ActivityTransactionGrouper).
9
+ #
10
+ # The versions a record saved in the step's transaction, up to the step's
11
+ # last source, made its changes there. A field's change follows what they
12
+ # recorded of it: each run of recorded changes is credited to the version
13
+ # that ended it, or the whole change to the last of the record's versions
14
+ # when what they recorded was not read. A record that appeared or
15
+ # disappeared is credited to its own create or destroy. Any other row keeps
16
+ # the step's source: a record that joined a collection or became a to-one
17
+ # target through another record's change, for one.
18
+ #
19
+ # With recorded changes read, the part of a field's change that those
20
+ # versions did not record is split off and credited to an unversioned
21
+ # source. It was saved without a version, as with `update_columns`, and
22
+ # history reads it into the state the next version stores, or the current
23
+ # row, so it shows up beside the change before it. Only what the versions
24
+ # show is split off. The row stays whole where they cannot:
25
+ #
26
+ # - a version that recorded nothing, such as a `touch`, or a table without
27
+ # `object_changes`;
28
+ # - a column PaperTrail is told not to record (see RecordedColumns);
29
+ # - a field a create left out, which held its default when created;
30
+ # - the start of a transaction that began before the history's start (see
31
+ # PreparedHistoryLoader#reload), whose earlier versions were not read.
32
+ class ChangeAttribution
33
+ # A transaction's boundaries, in the order the history kept them. Every
34
+ # step the transaction opens shares the one list and reads the boundaries
35
+ # before its own sources, so a long transaction costs one list rather
36
+ # than one for each step. A record's boundaries are found through an
37
+ # index, built when rows are first read, once the history is complete.
38
+ # A step's own sources are kept the same way, so a transaction group's
39
+ # rows name each source's record once rather than once for each record.
40
+ class Transaction
41
+ #: (?Array[ActivityBoundary]) -> void
42
+ def initialize(boundaries = [])
43
+ @boundaries = boundaries.dup
44
+ end
45
+
46
+ #: (ActivityBoundary) -> void
47
+ def add(boundary)
48
+ @boundaries << boundary
49
+ @positions = nil
50
+ end
51
+
52
+ #: () -> Integer
53
+ def length = @boundaries.length
54
+
55
+ # The record's boundaries among the first `count`, in order. The block
56
+ # names a boundary's record. The index is built whole before it is
57
+ # kept, so readers on two threads build the same one.
58
+ #: (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
59
+ def of(key, count, &identify)
60
+ positions = @positions ||= index(identify)
61
+ positions.fetch(key, []).take_while { |position| position < count }
62
+ .map { |position| @boundaries.fetch(position) }
63
+ end
64
+
65
+ private
66
+
67
+ # @rbs @boundaries: Array[ActivityBoundary]
68
+ # @rbs @positions: Hash[Array[String], Array[Integer]]?
69
+
70
+ #: (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
71
+ def index(identify)
72
+ @boundaries.each_index.group_by { |position| identify.call(@boundaries.fetch(position)) }
73
+ end
74
+ end
75
+
76
+ # `root` is the record the timeline is about, which rows name by leaving
77
+ # `record` nil. `transaction` holds the boundaries of the step's
78
+ # transaction, of which the first `preceding` came before its sources;
79
+ # `complete` says whether the history holds every version that
80
+ # transaction saved before them.
81
+ #: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
82
+ def initialize(root:, sources:, complete:, transaction:, preceding: transaction.length)
83
+ @root = root
84
+ @sources = Transaction.new(sources)
85
+ @complete = complete
86
+ @transaction = transaction
87
+ @preceding = preceding
88
+ @versions = {} #: Hash[Array[String], Array[ActivityBoundary]]
89
+ freeze
90
+ end
91
+
92
+ # The same transaction, read through a transaction group's sources.
93
+ #: (Array[ActivityBoundary]) -> ChangeAttribution
94
+ def with_sources(sources)
95
+ self.class.new(root: @root, sources: sources, complete: @complete,
96
+ transaction: @transaction, preceding: @preceding)
97
+ end
98
+
99
+ # The row as the rows it splits into, each credited to its change's
100
+ # source: one row, unless part of its change was saved without a version.
101
+ #: (ChangeRow) -> Array[ChangeRow]
102
+ def call(row)
103
+ versions = versions_of(row.record || @root)
104
+ return [row] if versions.empty?
105
+
106
+ case row.change
107
+ when :changed then changed(row, versions)
108
+ when :added then added(row, versions)
109
+ else [removed(row, versions)]
110
+ end
111
+ end
112
+
113
+ private
114
+
115
+ # @rbs @root: RecordReference
116
+ # @rbs @sources: Transaction
117
+ # @rbs @complete: bool
118
+ # @rbs @transaction: Transaction
119
+ # @rbs @preceding: Integer
120
+ # @rbs @versions: Hash[Array[String], Array[ActivityBoundary]]
121
+
122
+ # A field's change follows what the record's versions recorded of it,
123
+ # from the value the row starts at (see #relevant): each run of recorded
124
+ # changes is one row, credited to the version that ended it, and a value
125
+ # that moved where they do not meet was saved without a version. Where
126
+ # the row's start leads to no version, the move to the first of them is
127
+ # told apart only when the history holds the whole transaction.
128
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
129
+ def changed(row, versions)
130
+ touched = recorded_changes(versions, row.attribute)
131
+ return [credit(row, versions.last)] if touched.nil?
132
+
133
+ relevant = relevant(touched, row.from)
134
+ return unrecorded(row, versions) if relevant.empty?
135
+
136
+ trusted = @complete || relevant.length < touched.length
137
+ rows_for(row, chain(row.from, row.to, relevant, trusted), :changed)
138
+ end
139
+
140
+ # The changes that make up the row's: from the last one that left the
141
+ # row's starting value; or else those after the last that reached it,
142
+ # which an earlier step reported; or else all of them.
143
+ #: (Array[[ActivityBoundary, ValueChange]], untyped) -> Array[[ActivityBoundary, ValueChange]]
144
+ def relevant(touched, start)
145
+ leaving = touched.rindex { |_version, change| change.from == start }
146
+ return touched.drop(leaving) if leaving
147
+
148
+ reaching = touched.rindex { |_version, change| change.to == start }
149
+ reaching ? touched.drop(reaching + 1) : touched
150
+ end
151
+
152
+ # A field none of the versions recorded changed without one, when they
153
+ # record every change of it they make.
154
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
155
+ def unrecorded(row, versions)
156
+ return [credit(row, versions.last)] unless @complete && recorded_column?(row)
157
+
158
+ [credit(row, unversioned(row))]
159
+ end
160
+
161
+ # Only a record's own create says what it was created with. A field the
162
+ # create left out held its default, which no version records, so a value
163
+ # there can be the default or a later write: the row stays whole, or runs
164
+ # from nothing to what the versions after the create recorded.
165
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
166
+ def added(row, versions)
167
+ index = versions.index { |version| version.event == 'create' }
168
+ return [row] unless index
169
+
170
+ created = versions.drop(index)
171
+ touched = recorded_changes(created, row.attribute)
172
+ return [credit(row, created.first)] if touched.nil? || touched.empty?
173
+
174
+ rows_for(row, chain(nil, row.to, touched, false), :added)
175
+ end
176
+
177
+ # The value's path from `start` to `finish` as links of [from, to,
178
+ # version], with nil for no version: each recorded change, and between
179
+ # them whatever moved without one. A first change that does not start
180
+ # where the row does joins the row's start unless `trusted`.
181
+ #: (untyped, untyped, Array[[ActivityBoundary, ValueChange]], bool) -> Array[[untyped, untyped, ActivityBoundary?]]
182
+ def chain(start, finish, touched, trusted)
183
+ links = [] #: Array[[untyped, untyped, ActivityBoundary?]]
184
+ value = start
185
+ touched.each_with_index do |(version, change), index|
186
+ value = bridge(links, value, change.from) if index.positive? || trusted
187
+ links << link(value, change.to, version)
188
+ value = change.to
189
+ end
190
+ bridge(links, value, finish)
191
+ merge(merge(links).reject { |from, to, _version| from == to })
192
+ end
193
+
194
+ # A move from `value` to `to` that no version recorded, as a link; returns
195
+ # where it ends.
196
+ #: (Array[[untyped, untyped, ActivityBoundary?]], untyped, untyped) -> untyped
197
+ def bridge(links, value, to)
198
+ links << link(value, to, nil) unless to == value
199
+ to
200
+ end
201
+
202
+ #: (untyped, untyped, ActivityBoundary?) -> [untyped, untyped, ActivityBoundary?]
203
+ def link(from, to, version) = [from, to, version]
204
+
205
+ # Consecutive links of the same kind as one: recorded ones credited to the
206
+ # last of their versions.
207
+ #: (Array[[untyped, untyped, ActivityBoundary?]]) -> Array[[untyped, untyped, ActivityBoundary?]]
208
+ def merge(links)
209
+ merged = [] #: Array[[untyped, untyped, ActivityBoundary?]]
210
+ links.each do |from, to, version|
211
+ previous = merged.last
212
+ if previous && previous.last.nil? == version.nil?
213
+ merged[-1] = [previous.first, to, version]
214
+ else
215
+ merged << [from, to, version]
216
+ end
217
+ end
218
+ merged
219
+ end
220
+
221
+ # The first link keeps the row's own change, so an added field starts
222
+ # from nothing; its later values are changes to it.
223
+ #: (ChangeRow, Array[[untyped, untyped, ActivityBoundary?]], Symbol) -> Array[ChangeRow]
224
+ def rows_for(row, links, first)
225
+ links.each_with_index.map do |(from, to, version), index|
226
+ copy(row, change: index.zero? ? first : :changed, from: from, to: to,
227
+ source: version || unversioned(row))
228
+ end
229
+ end
230
+
231
+ #: (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
232
+ def removed(row, versions)
233
+ destroy = versions.find { |version| version.event == 'destroy' }
234
+ destroy ? credit(row, destroy) : row
235
+ end
236
+
237
+ # The changes the versions recorded of a field, each with its version:
238
+ # nil when one of them recorded nothing, or their changes were not read.
239
+ #: (Array[ActivityBoundary], String?) -> Array[[ActivityBoundary, ValueChange]]?
240
+ def recorded_changes(versions, name)
241
+ changes = recorded(versions)
242
+ return unless changes
243
+
244
+ touched = [] #: Array[[ActivityBoundary, ValueChange]]
245
+ versions.each_with_index do |version, index|
246
+ change = changes.fetch(index)[name]
247
+ touched << [version, change] if change
248
+ end
249
+ touched
250
+ end
251
+
252
+ # A row about a whole record has no field name, which no version records.
253
+ #: (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
254
+ def recorded(versions)
255
+ return unless versions.all?(&:recorded_changes?)
256
+
257
+ changes = versions.filter_map(&:recorded_changes)
258
+ changes if changes.length == versions.length
259
+ end
260
+
261
+ #: (ChangeRow) -> bool
262
+ def recorded_column?(row)
263
+ RecordedColumns.recorded?(Support.constant((row.record || @root).type), row.attribute)
264
+ rescue NameError
265
+ false
266
+ end
267
+
268
+ # The record's boundaries in the step's transaction, up to its last
269
+ # source, read once for each record.
270
+ #: (RecordReference) -> Array[ActivityBoundary]
271
+ def versions_of(reference)
272
+ key = identity(reference)
273
+ @versions.fetch(key) do
274
+ identify = ->(boundary) { identity(boundary.record) }
275
+ earlier = @transaction.of(key, @preceding, &identify)
276
+ @versions[key] = earlier + @sources.of(key, @sources.length, &identify)
277
+ end
278
+ end
279
+
280
+ # A record's base class and id, which name its row whichever subclass a
281
+ # snapshot or a version gives.
282
+ #: (RecordReference) -> Array[String]
283
+ def identity(reference)
284
+ [base_name(reference.type), reference.id.to_s]
285
+ end
286
+
287
+ #: (String) -> String
288
+ def base_name(type)
289
+ Support.constant(type).base_class.name
290
+ rescue NameError
291
+ type
292
+ end
293
+
294
+ #: (ChangeRow) -> ActivityBoundary
295
+ def unversioned(row)
296
+ reference = row.record || @root
297
+ ActivityBoundary.unversioned(item_type: base_name(reference.type), item_id: reference.id)
298
+ end
299
+
300
+ #: (ChangeRow, ActivityBoundary) -> ChangeRow
301
+ def credit(row, source)
302
+ copy(row, source: source)
303
+ end
304
+
305
+ #: (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
306
+ def copy(row, source:, change: row.change, from: row.from, to: row.to)
307
+ ChangeRow.new(
308
+ change: change, association_path: row.association_path,
309
+ association_kind: row.association_kind, record: row.record,
310
+ attribute: row.attribute, from: from, to: to, source: source
311
+ )
312
+ end
313
+ end
314
+ end
@@ -15,7 +15,11 @@ module PaperTrailDiff
15
15
  attr_reader :attribute #: String?
16
16
  attr_reader :from #: untyped
17
17
  attr_reader :to #: untyped
18
- # The step's source boundary: for a transaction group, its first event.
18
+ # The event that made the change: the version of the row's record that
19
+ # recorded it, or a source of kind `:unversioned` for a change saved
20
+ # without a version. A row the step's own events do not account for, such
21
+ # as a record joining a collection through another record's change, names
22
+ # the step's source boundary.
19
23
  attr_reader :source #: ActivityBoundary
20
24
 
21
25
  #: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
@@ -33,6 +37,14 @@ module PaperTrailDiff
33
37
  freeze
34
38
  end
35
39
 
40
+ # Whether the change was saved without a version, such as with
41
+ # `update_columns`, which PaperTrail never recorded. Only told apart with
42
+ # `recorded_changes: true`.
43
+ #: () -> bool
44
+ def unversioned?
45
+ source.unversioned?
46
+ end
47
+
36
48
  # The source's identifying fields sit beside the change rather than nested,
37
49
  # so the hash is one row of a table as it stands.
38
50
  #: () -> Hash[Symbol, untyped]
@@ -65,29 +77,36 @@ module PaperTrailDiff
65
77
  #
66
78
  # Two kinds of entry add nothing a row would show. One that only groups
67
79
  # others (an edited record, an association, a relationship) is left out,
68
- # because the rows under it name the same record. A blank field of an added
80
+ # because the rows under it name the same record. A nil field of an added
69
81
  # or removed record is left out too, because the record's own row already
70
- # says it appeared or disappeared.
82
+ # says it appeared or disappeared; an empty string or false is a value.
71
83
  class ChangeRows
72
84
  RECORD_ENTRIES = %i[record_added record_removed record_included].freeze
73
85
  private_constant :RECORD_ENTRIES
74
86
 
75
- #: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
76
- def self.call(diff, source:)
77
- new(source).call(diff)
87
+ # `attribution` credits each row to the event that made its change, and
88
+ # can split one in two (see ChangeAttribution); without it, every row is
89
+ # credited to `source`.
90
+ #: (Diff, source: ActivityBoundary, ?attribution: ChangeAttribution?) -> Array[ChangeRow]
91
+ def self.call(diff, source:, attribution: nil)
92
+ new(source, attribution).call(diff)
78
93
  end
79
94
 
80
- #: (ActivityBoundary) -> void
81
- def initialize(source)
95
+ #: (ActivityBoundary, ChangeAttribution?) -> void
96
+ def initialize(source, attribution)
82
97
  @source = source
98
+ @attribution = attribution
83
99
  end
84
100
 
85
101
  #: (Diff) -> Array[ChangeRow]
86
102
  def call(diff)
87
103
  rows = [] #: Array[ChangeRow]
104
+ attribution = @attribution
88
105
  diff.each_entry do |entry|
89
106
  row = row_for(entry)
90
- rows << row if row
107
+ next unless row
108
+
109
+ attribution ? rows.concat(attribution.call(row)) : rows << row
91
110
  end
92
111
  rows.freeze
93
112
  end
@@ -95,6 +114,7 @@ module PaperTrailDiff
95
114
  private
96
115
 
97
116
  # @rbs @source: ActivityBoundary
117
+ # @rbs @attribution: ChangeAttribution?
98
118
 
99
119
  #: (TraversalEntry) -> ChangeRow?
100
120
  def row_for(entry)
@@ -115,7 +135,7 @@ module PaperTrailDiff
115
135
  # side, so a field's value goes on the side that has it.
116
136
  #: (TraversalEntry, String?) -> ChangeRow
117
137
  def presence_row(entry, attribute)
118
- value = attribute ? entry.value : nil
138
+ value = (entry.value if attribute)
119
139
  return row(entry, :added, attribute, nil, value) if entry.state == :after
120
140
 
121
141
  row(entry, :removed, attribute, value, nil)
@@ -138,7 +138,7 @@ module PaperTrailDiff
138
138
  #: (Array[[untyped, untyped]]) -> Array[untyped]
139
139
  def historical_versions(pairs)
140
140
  selected = pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }
141
- selected.uniq { |version| [version.class.name, version.id] }
141
+ selected.uniq { |version| Support.row_key(version) }
142
142
  end
143
143
 
144
144
  #: () -> Array[[untyped, untyped]]
@@ -193,9 +193,8 @@ module PaperTrailDiff
193
193
  def endpoint_requirements(pairs)
194
194
  requirements = {} #: Hash[untyped, bool]
195
195
  pairs.flatten.each_with_object(requirements) do |endpoint, collected|
196
- historical = Endpoint.version?(endpoint)
197
- model_class = historical ? RecordedClass.for(endpoint) : endpoint.class
198
- collected[model_class] = collected.fetch(model_class, false) || historical
196
+ model_class = RecordedClass.of_endpoint(endpoint)
197
+ collected[model_class] = collected.fetch(model_class, false) || Endpoint.version?(endpoint)
199
198
  end
200
199
  end
201
200
  end