paper_trail_diff 0.16.0 → 0.17.1

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 +581 -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 +329 -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 +197 -45
  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 +27 -16
  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 +194 -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 +114 -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 +10 -9
  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
@@ -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,16 +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
38
  partial_snapshotter: method(:partial_snapshot),
39
- record_transition: record_transition
39
+ record_transition: record_transition,
40
+ root_state: root_state
40
41
  )
41
42
  end
42
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.
43
48
  #: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
44
49
  def advance_root(root_endpoint, context_endpoint, previous_snapshot, event:)
50
+ return full_snapshot(root_endpoint, context_endpoint) if @tree.empty?
51
+
45
52
  handled, incremental = @root_refresher.call(
46
53
  root_endpoint,
47
54
  context_endpoint,
@@ -70,15 +77,12 @@ module PaperTrailDiff
70
77
  branches, event)
71
78
  end
72
79
 
73
- endpoints = [root_endpoint, context_endpoint]
74
- handled, incremental = incremental_event(endpoints, previous_snapshot, branches, event,
75
- isolated)
76
- return incremental if handled
77
-
78
- partial = partial_snapshot(root_endpoint, context_endpoint, branches)
79
- return full_snapshot(root_endpoint, context_endpoint) unless partial
80
-
81
- 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)
82
86
  end
83
87
 
84
88
  private
@@ -103,19 +107,6 @@ module PaperTrailDiff
103
107
  root ? branches | @traversal.habtm_paths(RecordedClass.for(root_endpoint)) : branches
104
108
  end
105
109
 
106
- #: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
107
- def incremental_event(endpoints, previous, branches, event, isolated)
108
- return [false, nil] unless isolated
109
-
110
- @event_refresher.call(
111
- endpoints.fetch(0),
112
- endpoints.fetch(1),
113
- previous,
114
- branches,
115
- event
116
- )
117
- end
118
-
119
110
  #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent) -> RecordSnapshot?
120
111
  def refresh_independent_branches( # rubocop:disable Metrics/MethodLength
121
112
  root_endpoint,
@@ -142,10 +133,15 @@ module PaperTrailDiff
142
133
  end
143
134
  return snapshot if remaining.empty?
144
135
 
145
- partial = partial_snapshot(root_endpoint, context_endpoint, remaining)
146
- return full_snapshot(root_endpoint, context_endpoint) unless partial
136
+ refreshed(root_endpoint, context_endpoint, snapshot, remaining)
137
+ end
147
138
 
148
- 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)
149
145
  end
150
146
 
151
147
  #: (untyped, untyped, Array[String]) -> RecordSnapshot?
@@ -0,0 +1,329 @@
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
+ # Whether the boundary is one of these, not merely one like it.
56
+ #: (ActivityBoundary) -> bool
57
+ def holds?(boundary)
58
+ @boundaries.any? { |held| held.equal?(boundary) }
59
+ end
60
+
61
+ # The record's boundaries among the first `count`, in order. The block
62
+ # names a boundary's record. The index is built whole before it is
63
+ # kept, so readers on two threads build the same one.
64
+ #: (Array[String], Integer) { (ActivityBoundary) -> Array[String] } -> Array[ActivityBoundary]
65
+ def of(key, count, &identify)
66
+ positions = @positions ||= index(identify)
67
+ positions.fetch(key, []).take_while { |position| position < count }
68
+ .map { |position| @boundaries.fetch(position) }
69
+ end
70
+
71
+ private
72
+
73
+ # @rbs @boundaries: Array[ActivityBoundary]
74
+ # @rbs @positions: Hash[Array[String], Array[Integer]]?
75
+
76
+ #: (^(ActivityBoundary) -> Array[String]) -> Hash[Array[String], Array[Integer]]
77
+ def index(identify)
78
+ @boundaries.each_index.group_by { |position| identify.call(@boundaries.fetch(position)) }
79
+ end
80
+ end
81
+
82
+ # `root` is the record the timeline is about, which rows name by leaving
83
+ # `record` nil. `transaction` holds the boundaries of the step's
84
+ # transaction, of which the first `preceding` came before its sources;
85
+ # `complete` says whether the history holds every version that
86
+ # transaction saved before them.
87
+ #: (root: RecordReference, sources: Array[ActivityBoundary], complete: bool, transaction: Transaction, ?preceding: Integer) -> void
88
+ def initialize(root:, sources:, complete:, transaction:, preceding: transaction.length)
89
+ @root = root
90
+ @sources = Transaction.new(sources)
91
+ @complete = complete
92
+ @transaction = transaction
93
+ @preceding = preceding
94
+ @versions = {} #: Hash[Array[String], Array[ActivityBoundary]]
95
+ freeze
96
+ end
97
+
98
+ # The same transaction, read through a transaction group's sources.
99
+ #: (Array[ActivityBoundary]) -> ChangeAttribution
100
+ def with_sources(sources)
101
+ self.class.new(root: @root, sources: sources, complete: @complete,
102
+ transaction: @transaction, preceding: @preceding)
103
+ end
104
+
105
+ # The row as the rows it splits into, each credited to its change's
106
+ # source: one row, unless part of its change was saved without a version.
107
+ #: (ChangeRow) -> Array[ChangeRow]
108
+ def call(row)
109
+ versions = versions_of(row.record || @root)
110
+ return [row] if versions.empty?
111
+
112
+ case row.change
113
+ when :changed then changed(row, versions)
114
+ when :added then added(row, versions)
115
+ else [removed(row, versions)]
116
+ end
117
+ end
118
+
119
+ private
120
+
121
+ # @rbs @root: RecordReference
122
+ # @rbs @sources: Transaction
123
+ # @rbs @complete: bool
124
+ # @rbs @transaction: Transaction
125
+ # @rbs @preceding: Integer
126
+ # @rbs @versions: Hash[Array[String], Array[ActivityBoundary]]
127
+
128
+ # A field's change follows what the record's versions recorded of it,
129
+ # from the value the row starts at (see #relevant): each run of recorded
130
+ # changes is one row, credited to the version that ended it, and a value
131
+ # that moved where they do not meet was saved without a version. Where
132
+ # the row's start leads to no version, the move to the first of them is
133
+ # told apart only when the history holds the whole transaction.
134
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
135
+ def changed(row, versions)
136
+ touched = recorded_changes(versions, row.attribute)
137
+ return [credit(row, versions.last)] if touched.nil?
138
+
139
+ relevant = relevant(touched, row)
140
+ return unrecorded(row, versions) if relevant.empty?
141
+
142
+ trusted = @complete || relevant.length < touched.length
143
+ rows_for(row, chain(row.from, row.to, relevant, trusted), :changed)
144
+ end
145
+
146
+ # The changes that make up the row's: from the last one that left the
147
+ # row's starting value; or else those after the last that reached it,
148
+ # which an earlier step reported; or else all of them, which for a root's
149
+ # own field are only the ones its sources saved. A step starts from the
150
+ # state before its source, and a root's fields are read at each of its
151
+ # versions, so the root versions its transaction saved before the sources
152
+ # are already in that state. A related record's fields are read as the
153
+ # transaction began, so those versions still count.
154
+ #: (Array[[ActivityBoundary, ValueChange]], ChangeRow) -> Array[[ActivityBoundary, ValueChange]]
155
+ def relevant(touched, row)
156
+ start = row.from
157
+ leaving = touched.rindex { |_version, change| change.from == start }
158
+ return touched.drop(leaving) if leaving
159
+
160
+ reaching = touched.rindex { |_version, change| change.to == start }
161
+ return touched.drop(reaching + 1) if reaching
162
+ return touched if row.record
163
+
164
+ touched.select { |version, _change| @sources.holds?(version) }
165
+ end
166
+
167
+ # A field none of the versions recorded changed without one, when they
168
+ # record every change of it they make.
169
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
170
+ def unrecorded(row, versions)
171
+ return [credit(row, versions.last)] unless @complete && recorded_column?(row)
172
+
173
+ [credit(row, unversioned(row))]
174
+ end
175
+
176
+ # Only a record's own create says what it was created with. A field the
177
+ # create left out held its default, which no version records, so a value
178
+ # there can be the default or a later write: the row stays whole, or runs
179
+ # from nothing to what the versions after the create recorded.
180
+ #: (ChangeRow, Array[ActivityBoundary]) -> Array[ChangeRow]
181
+ def added(row, versions)
182
+ index = versions.index { |version| version.event == 'create' }
183
+ return [row] unless index
184
+
185
+ created = versions.drop(index)
186
+ touched = recorded_changes(created, row.attribute)
187
+ return [credit(row, created.first)] if touched.nil? || touched.empty?
188
+
189
+ rows_for(row, chain(nil, row.to, touched, false), :added)
190
+ end
191
+
192
+ # The value's path from `start` to `finish` as links of [from, to,
193
+ # version], with nil for no version: each recorded change, and between
194
+ # them whatever moved without one. A first change that does not start
195
+ # where the row does joins the row's start unless `trusted`.
196
+ #: (untyped, untyped, Array[[ActivityBoundary, ValueChange]], bool) -> Array[[untyped, untyped, ActivityBoundary?]]
197
+ def chain(start, finish, touched, trusted)
198
+ links = [] #: Array[[untyped, untyped, ActivityBoundary?]]
199
+ value = start
200
+ touched.each_with_index do |(version, change), index|
201
+ value = bridge(links, value, change.from) if index.positive? || trusted
202
+ links << link(value, change.to, version)
203
+ value = change.to
204
+ end
205
+ bridge(links, value, finish)
206
+ merge(merge(links).reject { |from, to, _version| from == to })
207
+ end
208
+
209
+ # A move from `value` to `to` that no version recorded, as a link; returns
210
+ # where it ends.
211
+ #: (Array[[untyped, untyped, ActivityBoundary?]], untyped, untyped) -> untyped
212
+ def bridge(links, value, to)
213
+ links << link(value, to, nil) unless to == value
214
+ to
215
+ end
216
+
217
+ #: (untyped, untyped, ActivityBoundary?) -> [untyped, untyped, ActivityBoundary?]
218
+ def link(from, to, version) = [from, to, version]
219
+
220
+ # Consecutive links of the same kind as one: recorded ones credited to the
221
+ # last of their versions.
222
+ #: (Array[[untyped, untyped, ActivityBoundary?]]) -> Array[[untyped, untyped, ActivityBoundary?]]
223
+ def merge(links)
224
+ merged = [] #: Array[[untyped, untyped, ActivityBoundary?]]
225
+ links.each do |from, to, version|
226
+ previous = merged.last
227
+ if previous && previous.last.nil? == version.nil?
228
+ merged[-1] = [previous.first, to, version]
229
+ else
230
+ merged << [from, to, version]
231
+ end
232
+ end
233
+ merged
234
+ end
235
+
236
+ # The first link keeps the row's own change, so an added field starts
237
+ # from nothing; its later values are changes to it.
238
+ #: (ChangeRow, Array[[untyped, untyped, ActivityBoundary?]], Symbol) -> Array[ChangeRow]
239
+ def rows_for(row, links, first)
240
+ links.each_with_index.map do |(from, to, version), index|
241
+ copy(row, change: index.zero? ? first : :changed, from: from, to: to,
242
+ source: version || unversioned(row))
243
+ end
244
+ end
245
+
246
+ #: (ChangeRow, Array[ActivityBoundary]) -> ChangeRow
247
+ def removed(row, versions)
248
+ destroy = versions.find { |version| version.event == 'destroy' }
249
+ destroy ? credit(row, destroy) : row
250
+ end
251
+
252
+ # The changes the versions recorded of a field, each with its version:
253
+ # nil when one of them recorded nothing, or their changes were not read.
254
+ #: (Array[ActivityBoundary], String?) -> Array[[ActivityBoundary, ValueChange]]?
255
+ def recorded_changes(versions, name)
256
+ changes = recorded(versions)
257
+ return unless changes
258
+
259
+ touched = [] #: Array[[ActivityBoundary, ValueChange]]
260
+ versions.each_with_index do |version, index|
261
+ change = changes.fetch(index)[name]
262
+ touched << [version, change] if change
263
+ end
264
+ touched
265
+ end
266
+
267
+ # A row about a whole record has no field name, which no version records.
268
+ #: (Array[ActivityBoundary]) -> Array[Hash[untyped, ValueChange]]?
269
+ def recorded(versions)
270
+ return unless versions.all?(&:recorded_changes?)
271
+
272
+ changes = versions.filter_map(&:recorded_changes)
273
+ changes if changes.length == versions.length
274
+ end
275
+
276
+ #: (ChangeRow) -> bool
277
+ def recorded_column?(row)
278
+ RecordedColumns.recorded?(Support.constant((row.record || @root).type), row.attribute)
279
+ rescue NameError
280
+ false
281
+ end
282
+
283
+ # The record's boundaries in the step's transaction, up to its last
284
+ # source, read once for each record.
285
+ #: (RecordReference) -> Array[ActivityBoundary]
286
+ def versions_of(reference)
287
+ key = identity(reference)
288
+ @versions.fetch(key) do
289
+ identify = ->(boundary) { identity(boundary.record) }
290
+ earlier = @transaction.of(key, @preceding, &identify)
291
+ @versions[key] = earlier + @sources.of(key, @sources.length, &identify)
292
+ end
293
+ end
294
+
295
+ # A record's base class and id, which name its row whichever subclass a
296
+ # snapshot or a version gives.
297
+ #: (RecordReference) -> Array[String]
298
+ def identity(reference)
299
+ [base_name(reference.type), reference.id.to_s]
300
+ end
301
+
302
+ #: (String) -> String
303
+ def base_name(type)
304
+ Support.constant(type).base_class.name
305
+ rescue NameError
306
+ type
307
+ end
308
+
309
+ #: (ChangeRow) -> ActivityBoundary
310
+ def unversioned(row)
311
+ reference = row.record || @root
312
+ ActivityBoundary.unversioned(item_type: base_name(reference.type), item_id: reference.id)
313
+ end
314
+
315
+ #: (ChangeRow, ActivityBoundary) -> ChangeRow
316
+ def credit(row, source)
317
+ copy(row, source: source)
318
+ end
319
+
320
+ #: (ChangeRow, source: ActivityBoundary, ?change: Symbol, ?from: untyped, ?to: untyped) -> ChangeRow
321
+ def copy(row, source:, change: row.change, from: row.from, to: row.to)
322
+ ChangeRow.new(
323
+ change: change, association_path: row.association_path,
324
+ association_kind: row.association_kind, record: row.record,
325
+ attribute: row.attribute, from: from, to: to, source: source
326
+ )
327
+ end
328
+ end
329
+ 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
@@ -86,7 +86,7 @@ module PaperTrailDiff
86
86
  #: (?prefix: String) -> Array[String]
87
87
  def paths(prefix: '')
88
88
  children.flat_map do |name, subtree|
89
- path = prefix.empty? ? name : "#{prefix}.#{name}"
89
+ path = Support.association_path(prefix, name)
90
90
  [path, *subtree.paths(prefix: path)]
91
91
  end.freeze
92
92
  end