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
@@ -10,24 +10,30 @@ module PaperTrailDiff
10
10
  # window reports only the events inside it, and closes on a final destroy,
11
11
  # or on the live row when nothing recorded follows it.
12
12
  class ActivityTimelineBuilder # rubocop:disable Metrics/ClassLength
13
- #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, view: ActivityView) -> void
14
- def initialize(record, range:, tree:, snapshotter:, view:)
13
+ # `traversal` holds the tree and reads its reflections; the adapter passes
14
+ # the one it reads every root with, so they are resolved once for a call
15
+ # rather than once for each root.
16
+ #: (untyped, range: TimelineRange, snapshotter: untyped, view: ActivityView, traversal: AssociationTraversal) -> void
17
+ def initialize(record, range:, snapshotter:, view:, traversal:)
15
18
  @view = view
16
19
  @record = record
17
20
  @to = range.to
18
21
  @range = range
19
- @tree = tree
22
+ @tree = traversal.tree
23
+ @traversal = traversal
20
24
  @snapshotter = snapshotter
25
+ # The root's own activity reads a version filter's answers from the plan.
26
+ @filter = (view.version_filter unless @tree.empty?)
21
27
  end
22
28
 
23
29
  #: () -> Array[ActivityStep]
24
30
  def build
25
- return window_steps if @range.time?
31
+ return steps_of(window_replay) if @range.time?
26
32
  return no_steps if @range.unresolved?
27
- return build_to_current if Endpoint.record?(@to)
33
+ return steps_of(current_replay) if Endpoint.record?(@to)
28
34
 
29
35
  Endpoint.validate!(@to)
30
- build_between_versions
36
+ steps_of(version_replay)
31
37
  end
32
38
 
33
39
  # The window the range covers once its edges have moved to transactions.
@@ -40,14 +46,11 @@ module PaperTrailDiff
40
46
  # activity snapshot pass.
41
47
  #: () -> Analysis
42
48
  def analyze
43
- return analyze_window if @range.time?
49
+ return analysis(window_replay) if @range.time?
44
50
  return Analysis.empty if @range.unresolved?
45
- return analyze_current if Endpoint.record?(@to)
51
+ return analysis(current_replay) if Endpoint.record?(@to)
46
52
 
47
- plan = @range.select_plan
48
- return Analysis.empty if plan.empty?
49
-
50
- build_analysis(plan, version_history(plan.reconstruction_versions))
53
+ analysis(version_replay)
51
54
  end
52
55
 
53
56
  private
@@ -56,8 +59,10 @@ module PaperTrailDiff
56
59
  # @rbs @to: untyped
57
60
  # @rbs @range: TimelineRange
58
61
  # @rbs @tree: AssociationTree
62
+ # @rbs @traversal: AssociationTraversal
59
63
  # @rbs @snapshotter: untyped
60
64
  # @rbs @view: ActivityView
65
+ # @rbs @filter: ActivityScopeFilter?
61
66
 
62
67
  #: () -> Array[ActivityStep]
63
68
  def no_steps
@@ -65,77 +70,109 @@ module PaperTrailDiff
65
70
  steps.freeze
66
71
  end
67
72
 
68
- # Every boundary in the span, filtered out or not. A filter narrows where the
69
- # span starts and ends, but the sequence inside it stays complete: dropping
70
- # boundaries would fold the changes they carried into a neighbouring step and
71
- # credit them to whoever made that one. A filter that keeps no version
72
- # leaves no span, as it does for a checkpoint timeline.
73
- #: () -> Array[ActivityStep]
74
- def build_between_versions
75
- plan = @range.select_plan
76
- return no_steps if plan.empty?
77
-
78
- root_versions = plan.reconstruction_versions
79
- activity_steps(version_history(root_versions), destroyed_boundary(root_versions), nil)
73
+ # Each kind of range replays into the same things, or into nil when it
74
+ # reports no step: its plan and history, the steps it reports, ending with
75
+ # the one that closes the range after its last event, the state it ends
76
+ # at, and the live record's snapshot and when it was read, which the root
77
+ # timeline's closing step reads.
78
+ #: (RootVersionPlan, ActivityHistory, ActivityStep?, RecordSnapshot?, ?RecordSnapshot?, ?untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
79
+ def replayed(plan, history, closing, final, snapshot = nil, captured_at = nil) # rubocop:disable Metrics/ParameterLists
80
+ steps = closing ? history.steps + [closing] : history.steps
81
+ [plan, history, steps, final, snapshot, captured_at] unless steps.empty?
80
82
  end
81
83
 
82
- # Activity from the first to the last of the root versions.
83
- #: (Array[untyped]) -> ActivityHistory
84
- def version_history(root_versions)
85
- snapshots = prepare_history(root_versions)
86
- events = collect_events(root_versions, snapshots, range_end: root_versions.last)
87
- replay(root_versions, events, snapshots)
84
+ #: ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Array[ActivityStep]
85
+ def steps_of(replay)
86
+ replay ? present(replay.fetch(2)) : no_steps
88
87
  end
89
88
 
90
- #: () -> Array[ActivityStep]
91
- def build_to_current
92
- _plan, history, snapshot, boundary = current_history
93
- activity_steps(history, boundary, snapshot)
89
+ # A range that reports no step is empty, whatever its replay read: a
90
+ # version filter may keep nothing in it, or only the version that ends it,
91
+ # which opens no step, and a range may run from a version to itself.
92
+ #: ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Analysis
93
+ def analysis(replay)
94
+ return Analysis.empty unless replay
95
+
96
+ plan, history, steps, final, snapshot, captured_at = replay
97
+ Analysis.new(
98
+ diff: Engine.compare(history.first_snapshot, final),
99
+ timeline: ActivityRootSteps.call(plan, history.root_snapshots, closing_snapshot: snapshot,
100
+ captured_at: captured_at),
101
+ activity_timeline: present(steps),
102
+ from_snapshot: history.first_snapshot,
103
+ to_snapshot: final
104
+ )
94
105
  end
95
106
 
96
- #: () -> Analysis
97
- def analyze_current
98
- plan, history, snapshot, boundary = current_history
99
- analysis(plan, history, final: boundary ? snapshot : history.last_snapshot,
100
- steps: activity_steps(history, boundary, snapshot),
101
- closing_snapshot: snapshot, captured_at: boundary&.recorded_at)
107
+ # Every boundary between the endpoints, filtered out or not: dropping one
108
+ # would fold the change it carried into a neighbouring step and credit it
109
+ # to whoever made that one. A version filter decides only which of the
110
+ # steps are reported (see #reported?). Only the activity view gains the
111
+ # closing removal. The endpoint diff and the root timeline keep their
112
+ # `compare` and `timeline` semantics, under which the state at a destroy
113
+ # version is the state before the deletion.
114
+ #: () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
115
+ def version_replay
116
+ plan = select_plan
117
+ history = history_until(plan)
118
+ replayed(plan, history, closing_step(history, plan), history.last_snapshot)
119
+ end
120
+
121
+ # Activity replays every root version in the range, even those a version
122
+ # filter leaves out, so that each change it keeps is read as the whole
123
+ # history shows it. Only a window reads a context: an explicit range
124
+ # always holds a version.
125
+ #: () -> RootVersionPlan
126
+ def select_plan = @range.select_plan(context_required: !@tree.empty?, whole: true)
127
+
128
+ # Whether the event's step is reported: it is inside the range, and a
129
+ # version filter keeps it. With associations the filter keeps whole
130
+ # transactions (see ActivityScopeFilter). On the root alone it keeps the
131
+ # root's versions, as `timeline` does, and so does a plan without one, but
132
+ # for the version it holds only to reveal the last change in it.
133
+ #: (ActivityEvent, RootVersionPlan) -> bool
134
+ def reported?(event, plan)
135
+ return false unless @range.include?(event.version)
136
+
137
+ filter = @filter
138
+ filter ? filter.kept?(event.version) : !event.root? || plan.mutation?(event.version)
102
139
  end
103
140
 
104
141
  # The explicit live endpoint and a batch's live closing endpoint use the
105
- # same selected plan. A version filter can close earlier, on its successor.
106
- #: () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
107
- def current_history
142
+ # same selected plan, which replays every version through to the current
143
+ # record, a version filter or not.
144
+ #: () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
145
+ def current_replay
108
146
  validate_current_range!
109
- plan = @range.select_plan
110
- return empty_history(plan) if plan.empty?
111
-
112
- snapshot, captured_at = capture_current if plan.closing_record
147
+ plan = select_plan
148
+ snapshot, captured_at = capture_current
113
149
  history = history_until(plan, snapshot, captured_at)
114
- boundary = current_boundary(captured_at) if plan.closing_record
115
- [plan, history, snapshot, boundary]
150
+ live_replay(plan, history, @to, captured_at, snapshot)
116
151
  end
117
152
 
118
- # Events up to the instant the current record was read. A range that a
119
- # version filter closes earlier ends at that version, with no snapshot.
120
- #: (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
121
- def history_until(plan, snapshot, captured_at)
122
- versions = plan.reconstruction_versions
123
- snapshots = prepare_history(versions, end_at: captured_at)
124
- events = collect_events(versions, snapshots, range_end: captured_at || versions.last)
125
- replay(versions, events, snapshots, current: plan.closing_record, closing: snapshot)
153
+ # A range that closes after its last event ends at what closed it: the
154
+ # live row, or nothing after a destroy, where no live row is read. One
155
+ # that does not ends at the state its last reported step reached.
156
+ #: (RootVersionPlan, ActivityHistory, untyped, untyped, RecordSnapshot?) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
157
+ def live_replay(plan, history, live, captured_at, snapshot)
158
+ closing = closing_step(history, plan, live, captured_at, snapshot)
159
+ replayed(plan, history, closing, closing ? snapshot : history.last_snapshot, snapshot,
160
+ captured_at)
126
161
  end
127
162
 
128
- # Without a closing boundary nothing reads the closing pair, so its
129
- # mutations cannot change an answer.
130
- # mutant:disable
131
- #: (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
132
- def empty_history(plan)
133
- [plan, ActivityHistory.empty, nil, nil]
163
+ #: (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
164
+ def history_until(plan, snapshot = nil, captured_at = nil)
165
+ events, snapshots = range_events(plan, captured_at)
166
+ replay(plan, events, snapshots, current: plan.closing_record, closing: snapshot)
134
167
  end
135
168
 
136
- #: (untyped) -> ActivityBoundary
137
- def current_boundary(captured_at)
138
- ActivityBoundary.current(@to, captured_at: captured_at, recorded: root_recorded)
169
+ # The range's events up to its last root version, or to the instant the
170
+ # live record it closes on was read, with the history they are read from.
171
+ #: (RootVersionPlan, untyped) -> [Array[ActivityEvent], untyped]
172
+ def range_events(plan, captured_at)
173
+ versions = plan.reconstruction_versions
174
+ snapshots = prepare_history(versions, end_at: captured_at)
175
+ [collect_events(versions, snapshots, range_end: captured_at || versions.last), snapshots]
139
176
  end
140
177
 
141
178
  #: () -> [RecordSnapshot?, untyped]
@@ -153,178 +190,88 @@ module PaperTrailDiff
153
190
  reject_live_habtm!
154
191
  end
155
192
 
156
- # Appends the transition into an explicit closing boundary, which is either
157
- # a requested current record or the absence a final root destroy leaves.
158
- # Either follows the root versions, which are themselves events, so the
159
- # last boundary the history kept opens it.
160
- #: (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
161
- def activity_steps(history, final_boundary, final_snapshot)
162
- return present(history.steps) unless final_boundary
163
-
164
- last_boundary = history.last_boundary #: ActivityBoundary
165
- present(history.steps + [step_from_last(history, last_boundary, final_boundary,
166
- final_snapshot)])
167
- end
168
-
169
- # A destroyed root has no later version, but its own event states that
170
- # nothing follows it, so the removal can still close the timeline.
171
- #: (Array[untyped]) -> ActivityBoundary?
172
- def destroyed_boundary(root_versions)
173
- version = root_versions.last
174
- return unless version.event == 'destroy'
175
-
176
- ActivityBoundary.destroyed(version, recorded: root_recorded)
177
- end
178
-
179
- # Only the activity view gains the closing removal. The endpoint diff and
180
- # the root timeline keep their `compare` and `timeline` semantics, under
181
- # which the state at a destroy version is the state before the deletion.
182
- #: (RootVersionPlan, ActivityHistory) -> Analysis
183
- def build_analysis(plan, history)
184
- steps = activity_steps(history, destroyed_boundary(plan.reconstruction_versions), nil)
185
- analysis(plan, history, final: history.last_snapshot, steps: steps)
186
- end
187
-
188
- #: () -> Array[ActivityStep]
189
- def window_steps
190
- history, _plan, closing, = window_history
191
- present(closing ? history.steps + [closing] : history.steps)
192
- end
193
-
194
- #: () -> Analysis
195
- def analyze_window
196
- history, plan, closing, closing_snapshot, captured_at = window_history
197
- analysis(plan, history,
198
- final: window_final_snapshot(history, closing, closing_snapshot),
199
- steps: present(closing ? history.steps + [closing] : history.steps),
200
- closing_snapshot: closing_snapshot, captured_at: captured_at)
201
- end
202
-
203
- # A window with a closing step ends at what closed it: the live row, or
204
- # nothing after a destroy, where no live row is read. One that ends before
205
- # a later event ends at the state that event found.
206
- #: (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
207
- def window_final_snapshot(history, closing, closing_snapshot)
208
- closing ? closing_snapshot : history.last_snapshot
209
- end
210
-
211
- #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
212
- def window_history
213
- plan = @range.select_plan(context_required: !@tree.empty?)
214
- reject_live_habtm! if plan.closing_record
215
- return empty_window(plan) if plan.empty? && !plan.closing_record
216
-
217
- # A window closing on current state runs to the instant it is captured,
218
- # not to the last root version, or descendants that moved after that
219
- # version would be missing from a report that claims to reach now.
220
- window_replay(plan, (Time.now.utc if plan.closing_record))
221
- end
222
-
223
- # Nothing reads a window's closing step, live snapshot, or capture time
224
- # when it reported nothing, so mutations of those cannot change an answer.
225
- # mutant:disable
226
- #: (RootVersionPlan) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
227
- def empty_window(plan)
228
- [ActivityHistory.empty, plan, nil, nil, nil]
229
- end
230
-
231
- # A window with no selected event reports nothing. Any other has a
232
- # boundary after its last one: the plan refuses a window that has no later
233
- # version, ends on no destroy, and does not close on the live row.
234
- #: (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
235
- def window_replay(plan, captured_at)
236
- versions = plan.reconstruction_versions
237
- snapshots = prepare_history(versions, end_at: captured_at)
238
- events = collect_events(versions, snapshots, range_end: captured_at || versions.last)
239
- selected = selected_events(events, plan)
240
- last = selected.last
241
- return empty_window(plan) unless last
242
-
243
- snapshot = window_live_snapshot(plan)
244
- history = replay(versions, events, snapshots, current: plan.closing_record, closing: snapshot)
245
- closing = window_closing(history, last, plan, captured_at, snapshot, events)
246
- [history, plan, closing, snapshot, captured_at]
247
- end
248
-
249
- # One live read serves both the closing activity step and the endpoint the
250
- # analysis reports, which would otherwise reconstruct the graph twice.
251
- #: (RootVersionPlan) -> RecordSnapshot?
252
- def window_live_snapshot(plan)
253
- record = plan.closing_record
254
- return unless record
255
-
256
- @snapshotter.call(record, record)
257
- end
258
-
259
- # Root versions inside the window that the plan does not report are context
260
- # rather than mutations: the version appended to reveal the last selected
261
- # change, and anything a filter excluded but the replay still walks. Neither
262
- # may be counted as a selected mutation. Descendant events are not filtered,
263
- # so window membership is the whole test for them.
264
- #: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
265
- def selected_events(events, plan)
266
- events.select do |event|
267
- @range.include?(event.version) && (!event.root? || plan.mutation?(event.version))
268
- end
269
- end
270
-
271
- # A window either closes on the absence its final destruction leaves, or on
272
- # current state when it reaches past everything recorded. Both are boundaries
273
- # no version can supply.
193
+ # A window with no selected event reports nothing, and so does one whose
194
+ # replay left out every event it selected, each of a record outside the
195
+ # tree throughout, such as a comment created outside a scope. Any other
196
+ # has a boundary after its last event: the plan refuses a window that has
197
+ # no later version, ends on no destroy, and does not close on the live row.
198
+ #
199
+ # A window closing on current state runs to the instant it is captured,
200
+ # not to the last root version, or descendants that moved after that
201
+ # version would be missing from a report that claims to reach now.
202
+ #: () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
203
+ def window_replay
204
+ plan = select_plan
205
+ live = plan.closing_record
206
+ reject_live_habtm! if live
207
+ window_activity(plan, live, (Time.now.utc if live)) unless plan.empty? && !live
208
+ end
209
+
210
+ # The live record is read only once something in the window is reported.
211
+ #: (RootVersionPlan, untyped, untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
212
+ def window_activity(plan, live, captured_at)
213
+ events, snapshots = range_events(plan, captured_at)
214
+ return unless events.any? { |event| reported?(event, plan) }
215
+
216
+ snapshot = (@snapshotter.call(live, live) if live)
217
+ history = replay(plan, events, snapshots, current: live, closing: snapshot)
218
+ live_replay(plan, history, live, captured_at, snapshot)
219
+ end
220
+
221
+ # The step that closes the range after its last event, which is reported
222
+ # as that event's step would be. It runs from the last boundary the
223
+ # history kept into one no version can supply: the live record the range
224
+ # closes on, or the absence a final root destroy leaves.
274
225
  #
275
226
  # Everything recorded means on every requested path, not only the root's
276
- # own versions. When an association changed after the window, its last
277
- # step already ends at that change, at the state the window left; closing
278
- # on current state would add the later change to a window it was not in.
279
- #: (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
280
- def window_closing(history, event, plan, captured_at, snapshot, events) # rubocop:disable Metrics/ParameterLists
281
- return window_destroyed_step(history, event) if terminal_destroy?(event)
282
- return unless plan.closing_record
283
- return if events.any? { |later| !@range.include?(later.version) }
284
-
285
- window_current_step(history, plan.closing_record, captured_at, snapshot)
286
- end
287
-
288
- #: (ActivityHistory, ActivityEvent) -> ActivityStep
289
- def window_destroyed_step(history, event)
290
- version = event.version
227
+ # own versions. When an association changed after a window, its last step
228
+ # already ends at that change, at the state the window left, and that
229
+ # change is the last kept event, outside the window; closing on current
230
+ # state would add it to a window it was not in. A plan that does not close
231
+ # on the current record holds a version after the window, which is such a
232
+ # change, or ends at a destruction.
233
+ #: (ActivityHistory, RootVersionPlan, ?untyped, ?untyped, ?RecordSnapshot?) -> ActivityStep?
234
+ def closing_step(history, plan, live = nil, captured_at = nil, snapshot = nil)
235
+ boundary = closing_boundary(history.last_event, plan, live, captured_at)
236
+ return unless boundary
237
+
238
+ last = history.last_boundary #: ActivityBoundary
291
239
  ActivityStep.between(
292
- from_boundary: ActivityBoundary.from_version(version, recorded: root_recorded),
293
- to_boundary: ActivityBoundary.destroyed(version, recorded: root_recorded),
294
- from_snapshot: history.root_snapshots.fetch(ActivityRootSteps.version_key(version)),
295
- to_snapshot: nil, retain: @view.retain?
240
+ from_boundary: last, to_boundary: boundary,
241
+ from_snapshot: history.last_event_snapshot, to_snapshot: snapshot,
242
+ retain: @view.retain?, attribution: history.last_attribution
296
243
  )
297
244
  end
298
245
 
299
- # The last boundary reached is where current state is compared from, which
300
- # is the final event rather than the final root version once descendants
301
- # have moved since it. A selected event is a boundary the history kept.
302
- #: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
303
- def window_current_step(history, record, captured_at, snapshot)
304
- previous = history.last_boundary #: ActivityBoundary
305
- current = ActivityBoundary.current(record, captured_at: captured_at, recorded: root_recorded)
306
- step_from_last(history, previous, current, snapshot)
307
- end
246
+ # Without a live record to close on, a range closes only on the root's
247
+ # destruction, and its last event is then the root's own: the version
248
+ # that ends an explicit range, or a window's version after it, or the
249
+ # destroy nothing follows.
250
+ #: (ActivityEvent?, RootVersionPlan, untyped, untyped) -> ActivityBoundary?
251
+ def closing_boundary(event, plan, live, captured_at)
252
+ return unless event && reported?(event, plan)
308
253
 
309
- #: (ActivityEvent) -> bool
310
- def terminal_destroy?(event)
311
- event.root? && event.version.event == 'destroy'
254
+ if live
255
+ ActivityBoundary.current(live, captured_at: captured_at, recorded: root_recorded)
256
+ elsif event.version.event == 'destroy'
257
+ ActivityBoundary.destroyed(event.version, recorded: root_recorded)
258
+ end
312
259
  end
313
260
 
314
261
  #: () -> void
315
262
  def reject_live_habtm!
316
- AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
263
+ @traversal.reject_live_habtm_activity!(@record.class)
317
264
  end
318
265
 
319
- #: () -> Array[String]?
266
+ #: () -> RecordedChangesReader?
320
267
  def root_recorded
321
- @view.recorded_attributes(root: true)
268
+ @view.recorded_reader(root: true)
322
269
  end
323
270
 
324
271
  # A window prepares from its start, explicit endpoints from their first
325
272
  # version.
326
- #: (Array[untyped], ?end_at: untyped) -> untyped
327
- def prepare_history(root_versions, end_at: nil)
273
+ #: (Array[untyped], end_at: untyped) -> untyped
274
+ def prepare_history(root_versions, end_at:)
328
275
  options = { start_at: @range.begin_time, end_at: end_at }.compact
329
276
  @snapshotter.prepare(@record, root_versions, **options)
330
277
  end
@@ -338,53 +285,51 @@ module PaperTrailDiff
338
285
  events = ActivityVersionCollector.new(
339
286
  @record,
340
287
  root_versions: root_versions,
341
- tree: @tree,
288
+ traversal: @traversal,
342
289
  prepared: snapshots.activity_index,
343
290
  range_start: @range.begin_time || root_versions.first,
344
291
  range_end: range_end
345
292
  ).call
346
- @range.time? ? events : ActivityTransactionGroups.before_closing(events, range_end)
293
+ events = ActivityTransactionGroups.before_closing(events, range_end) unless @range.time?
294
+ prepare_filter(snapshots, events)
295
+ events
296
+ end
297
+
298
+ # A version filter reads its answers for a batch's history once, for the
299
+ # first root that history serves.
300
+ #: (untyped, Array[ActivityEvent]) -> void
301
+ def prepare_filter(snapshots, events)
302
+ @filter&.prepare(snapshots.history, events.map(&:version))
347
303
  end
348
304
 
349
305
  # Events after the last root version read the root from the live record
350
- # when the range closes on it. Explicit endpoints report every step, as
351
- # their range includes every version.
352
- #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
353
- def replay(root_versions, events, snapshots, current: nil, closing: nil)
306
+ # when the range closes on it. Explicit endpoints report every step their
307
+ # plan does, as their range includes every version.
308
+ #: (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
309
+ def replay(plan, events, snapshots, current:, closing:)
354
310
  ActivityHistoryBuilder.new(
355
- root_versions, events, snapshots,
311
+ plan.reconstruction_versions, events, snapshots,
356
312
  current: current,
357
- include_step: ->(event) { @range.include?(event.version) },
313
+ include_step: ->(event) { reported?(event, plan) },
358
314
  view: @view,
359
- closing: closing
315
+ closing: closing,
316
+ root: root_reference
360
317
  ).call
361
318
  end
362
319
 
363
- # The step from the last boundary the history reached to one that closes
364
- # the range.
365
- #: (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
366
- def step_from_last(history, last_boundary, closing_boundary, closing_snapshot)
367
- ActivityStep.between(
368
- from_boundary: last_boundary, to_boundary: closing_boundary,
369
- from_snapshot: history.last_event_snapshot, to_snapshot: closing_snapshot,
370
- retain: @view.retain?
371
- )
320
+ # The root as a change row's `record` would name it. A root is a record,
321
+ # or a deleted one rebuilt from its destroy (see DeletedAnalysisBatch).
322
+ # A reference reads its type with `to_s`, so mutant cannot tell the class
323
+ # from its name here.
324
+ # mutant:disable
325
+ #: () -> RecordReference
326
+ def root_reference
327
+ RecordReference.new(type: @record.class.name, id: @record.id)
372
328
  end
373
329
 
374
330
  #: (Array[ActivityStep]) -> Array[ActivityStep]
375
331
  def present(steps)
376
332
  @view.present(steps).freeze
377
333
  end
378
-
379
- #: (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
380
- def analysis(plan, history, final:, steps:, **closing)
381
- Analysis.new(
382
- diff: Engine.compare(history.first_snapshot, final),
383
- timeline: ActivityRootSteps.call(plan, history.root_snapshots, **closing),
384
- activity_timeline: steps,
385
- from_snapshot: history.first_snapshot,
386
- to_snapshot: final
387
- )
388
- end
389
334
  end
390
335
  end
@@ -71,13 +71,15 @@ module PaperTrailDiff
71
71
  def merge(group)
72
72
  first = group.first #: ActivityStep
73
73
  last = group.last #: ActivityStep
74
+ sources = group.flat_map(&:sources)
74
75
  ActivityStep.between(
75
76
  from_boundary: first.from_boundary,
76
77
  to_boundary: last.to_boundary,
77
78
  from_snapshot: first.from_snapshot,
78
79
  to_snapshot: last.to_snapshot,
79
80
  retain: @retain,
80
- sources: group.flat_map(&:sources)
81
+ sources: sources,
82
+ attribution: first.attribution&.with_sources(sources)
81
83
  )
82
84
  end
83
85
  end