paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -2,18 +2,17 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Compares adjacent root and selected-descendant activity boundaries.
6
- class ActivityTimelineBuilder
7
- include ActivityGrouping
8
-
9
- #: (untyped, range: TimelineRange, tree: AssociationTree, snapshotter: untyped, snapshots: bool, group: Symbol?) -> void
10
- def initialize(record, range:, tree:, snapshotter:, snapshots:, group:) # rubocop:disable Metrics/ParameterLists
11
- ActivityGrouping.validate!(group)
12
- @snapshots = snapshots
13
- @group = group
14
- # Merging a group compares its outer states, so the snapshots must survive
15
- # the build even when the caller did not ask to keep them.
16
- @retain = snapshots || grouping?
5
+ # Compares adjacent root and selected-descendant activity boundaries, between
6
+ # explicit endpoints or over a wall-clock window. Both replay the range's
7
+ # events into steps the same way, and close on the live row the same way.
8
+ # They differ in what they report and what closes them: explicit endpoints
9
+ # report every step between them and close on the endpoint asked for; a
10
+ # window reports only the events inside it, and closes on a final destroy,
11
+ # or on the live row when nothing recorded follows it.
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:)
15
+ @view = view
17
16
  @record = record
18
17
  @to = range.to
19
18
  @range = range
@@ -23,7 +22,7 @@ module PaperTrailDiff
23
22
 
24
23
  #: () -> Array[ActivityStep]
25
24
  def build
26
- return time_builder.build if @range.time?
25
+ return window_steps if @range.time?
27
26
  return no_steps if @range.unresolved?
28
27
  return build_to_current if Endpoint.record?(@to)
29
28
 
@@ -31,20 +30,24 @@ module PaperTrailDiff
31
30
  build_between_versions
32
31
  end
33
32
 
34
- # Builds all three version-bounded views from one activity snapshot pass.
33
+ # The window the range covers once its edges have moved to transactions.
34
+ #: () -> TimeRange?
35
+ def window
36
+ @range.time_range
37
+ end
38
+
39
+ # Builds the endpoint diff, the root timeline, and the activity from one
40
+ # activity snapshot pass.
35
41
  #: () -> Analysis
36
42
  def analyze
37
- return time_builder.analyze if @range.time?
43
+ return analyze_window if @range.time?
38
44
  return Analysis.empty if @range.unresolved?
39
45
  return analyze_current if Endpoint.record?(@to)
40
46
 
41
47
  plan = @range.select_plan
42
48
  return Analysis.empty if plan.empty?
43
49
 
44
- root_versions = plan.reconstruction_versions
45
- prepare_history(root_versions)
46
- events = collect_events(root_versions)
47
- build_analysis(plan, events, event_history(root_versions, events))
50
+ build_analysis(plan, version_history(plan.reconstruction_versions))
48
51
  end
49
52
 
50
53
  private
@@ -54,7 +57,7 @@ module PaperTrailDiff
54
57
  # @rbs @range: TimelineRange
55
58
  # @rbs @tree: AssociationTree
56
59
  # @rbs @snapshotter: untyped
57
- # @rbs @snapshots: bool
60
+ # @rbs @view: ActivityView
58
61
 
59
62
  #: () -> Array[ActivityStep]
60
63
  def no_steps
@@ -73,56 +76,66 @@ module PaperTrailDiff
73
76
  return no_steps if plan.empty?
74
77
 
75
78
  root_versions = plan.reconstruction_versions
76
- prepare_history(root_versions)
77
- events = collect_events(root_versions)
78
- history = event_history(root_versions, events)
79
- activity_steps(history, events, destroyed_boundary(root_versions), nil)
79
+ activity_steps(version_history(root_versions), destroyed_boundary(root_versions), nil)
80
+ end
81
+
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)
80
88
  end
81
89
 
82
90
  #: () -> Array[ActivityStep]
83
91
  def build_to_current
84
- _plan, events, history, snapshot, boundary = current_history
85
- activity_steps(history, events, boundary, snapshot)
92
+ _plan, history, snapshot, boundary = current_history
93
+ activity_steps(history, boundary, snapshot)
86
94
  end
87
95
 
88
96
  #: () -> Analysis
89
97
  def analyze_current
90
- plan, events, history, snapshot, boundary = current_history
91
- final = boundary ? snapshot : history.last_snapshot
92
- Analysis.new(
93
- diff: Engine.compare(history.first_snapshot, final),
94
- timeline: ActivityRootSteps.call(
95
- plan, history.root_snapshots, closing_snapshot: snapshot,
96
- captured_at: boundary&.recorded_at
97
- ),
98
- activity_timeline: activity_steps(history, events, boundary, snapshot),
99
- from_snapshot: history.first_snapshot, to_snapshot: final
100
- )
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)
101
102
  end
102
103
 
103
104
  # The explicit live endpoint and a batch's live closing endpoint use the
104
105
  # same selected plan. A version filter can close earlier, on its successor.
105
- #: () -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
106
+ #: () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
106
107
  def current_history
107
108
  validate_current_range!
108
109
  plan = @range.select_plan
109
110
  return empty_history(plan) if plan.empty?
110
111
 
111
112
  snapshot, captured_at = capture_current if plan.closing_record
113
+ history = history_until(plan, snapshot, captured_at)
114
+ boundary = current_boundary(captured_at) if plan.closing_record
115
+ [plan, history, snapshot, boundary]
116
+ end
117
+
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)
112
122
  versions = plan.reconstruction_versions
113
- prepare_history(versions, end_at: captured_at)
114
- events = collect_events(versions, range_end: captured_at || versions.last)
115
- history = event_history(versions, events, current: plan.closing_record)
116
- boundary = ActivityBoundary.current(@to, captured_at: captured_at) if plan.closing_record
117
- [plan, events, history, snapshot, boundary]
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)
118
126
  end
119
127
 
120
- # Without a closing boundary nothing reads the events or the closing pair,
121
- # so their mutations cannot change an answer.
128
+ # Without a closing boundary nothing reads the closing pair, so its
129
+ # mutations cannot change an answer.
122
130
  # mutant:disable
123
- #: (RootVersionPlan) -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
131
+ #: (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
124
132
  def empty_history(plan)
125
- [plan, [], ActivityHistory.empty, nil, nil]
133
+ [plan, ActivityHistory.empty, nil, nil]
134
+ end
135
+
136
+ #: (untyped) -> ActivityBoundary
137
+ def current_boundary(captured_at)
138
+ ActivityBoundary.current(@to, captured_at: captured_at, recorded: root_recorded)
126
139
  end
127
140
 
128
141
  #: () -> [RecordSnapshot?, untyped]
@@ -137,49 +150,20 @@ module PaperTrailDiff
137
150
  end
138
151
 
139
152
  Endpoint.validate_pair!(@range.from, @to)
140
- AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
141
- end
142
-
143
- #: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
144
- def collect_events(
145
- root_versions,
146
- range_start: root_versions.first,
147
- range_end: root_versions.last
148
- )
149
- ActivityVersionCollector.new(
150
- @record,
151
- root_versions: root_versions,
152
- tree: @tree,
153
- prepared: (@snapshotter.activity_index if @snapshotter.respond_to?(:activity_index)),
154
- range_start: range_start,
155
- range_end: range_end
156
- ).call
157
- end
158
-
159
- #: (Array[untyped], ?end_at: untyped) -> void
160
- def prepare_history(root_versions, end_at: nil)
161
- return unless @snapshotter.respond_to?(:prepare)
162
- return @snapshotter.prepare(@record, root_versions) unless end_at
163
-
164
- @snapshotter.prepare(@record, root_versions, end_at: end_at)
153
+ reject_live_habtm!
165
154
  end
166
155
 
167
156
  # Appends the transition into an explicit closing boundary, which is either
168
157
  # a requested current record or the absence a final root destroy leaves.
169
- # Either follows the root versions, which are themselves events.
170
- #: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
171
- def activity_steps(history, events, final_boundary, final_snapshot)
172
- steps = history.steps.dup
173
- if final_boundary
174
- last_event = events.last #: ActivityEvent
175
- steps << ActivityStep.between(
176
- from_boundary: ActivityBoundary.from_version(last_event.version),
177
- to_boundary: final_boundary,
178
- from_snapshot: history.last_snapshot, to_snapshot: final_snapshot,
179
- retain: @retain
180
- )
181
- end
182
- group_steps(steps).freeze
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)])
183
167
  end
184
168
 
185
169
  # A destroyed root has no later version, but its own event states that
@@ -189,41 +173,218 @@ module PaperTrailDiff
189
173
  version = root_versions.last
190
174
  return unless version.event == 'destroy'
191
175
 
192
- ActivityBoundary.destroyed(version)
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.
274
+ #
275
+ # 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
291
+ 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?
296
+ )
297
+ end
298
+
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
308
+
309
+ #: (ActivityEvent) -> bool
310
+ def terminal_destroy?(event)
311
+ event.root? && event.version.event == 'destroy'
312
+ end
313
+
314
+ #: () -> void
315
+ def reject_live_habtm!
316
+ AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
317
+ end
318
+
319
+ #: () -> Array[String]?
320
+ def root_recorded
321
+ @view.recorded_attributes(root: true)
322
+ end
323
+
324
+ # A window prepares from its start, explicit endpoints from their first
325
+ # version.
326
+ #: (Array[untyped], ?end_at: untyped) -> untyped
327
+ def prepare_history(root_versions, end_at: nil)
328
+ options = { start_at: @range.begin_time, end_at: end_at }.compact
329
+ @snapshotter.prepare(@record, root_versions, **options)
330
+ end
331
+
332
+ # A window collects from its start, explicit endpoints from their first
333
+ # version. Explicit endpoints also stop before the rest of the closing
334
+ # version's transaction (see ActivityTransactionGroups.before_closing); a
335
+ # window keeps every event it collected and reports only those inside it.
336
+ #: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
337
+ def collect_events(root_versions, snapshots, range_end:)
338
+ events = ActivityVersionCollector.new(
339
+ @record,
340
+ root_versions: root_versions,
341
+ tree: @tree,
342
+ prepared: snapshots.activity_index,
343
+ range_start: @range.begin_time || root_versions.first,
344
+ range_end: range_end
345
+ ).call
346
+ @range.time? ? events : ActivityTransactionGroups.before_closing(events, range_end)
193
347
  end
194
348
 
195
- #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
196
- def event_history(root_versions, events, current: nil)
349
+ # 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)
197
354
  ActivityHistoryBuilder.new(
198
- root_versions,
199
- events,
200
- @snapshotter,
355
+ root_versions, events, snapshots,
201
356
  current: current,
202
- snapshots: @retain
357
+ include_step: ->(event) { @range.include?(event.version) },
358
+ view: @view,
359
+ closing: closing
203
360
  ).call
204
361
  end
205
362
 
206
- # Only the activity view gains the closing removal. The endpoint diff and
207
- # the root timeline keep their `compare` and `timeline` semantics, under
208
- # which the state at a destroy version is the state before the deletion.
209
- #: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
210
- def build_analysis(plan, events, history)
211
- Analysis.new(
212
- diff: Engine.compare(history.first_snapshot, history.last_snapshot),
213
- timeline: ActivityRootSteps.call(plan, history.root_snapshots),
214
- activity_timeline: activity_steps(
215
- history, events, destroyed_boundary(plan.reconstruction_versions), nil
216
- ),
217
- from_snapshot: history.first_snapshot,
218
- to_snapshot: history.last_snapshot
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?
219
371
  )
220
372
  end
221
373
 
222
- #: () -> TimeActivityTimelineBuilder
223
- def time_builder
224
- TimeActivityTimelineBuilder.new(@record, range: @range, tree: @tree,
225
- snapshotter: @snapshotter, snapshots: @snapshots,
226
- group: @group)
374
+ #: (Array[ActivityStep]) -> Array[ActivityStep]
375
+ def present(steps)
376
+ @view.present(steps).freeze
377
+ 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
+ )
227
388
  end
228
389
  end
229
390
  end
@@ -76,7 +76,8 @@ module PaperTrailDiff
76
76
  to_boundary: last.to_boundary,
77
77
  from_snapshot: first.from_snapshot,
78
78
  to_snapshot: last.to_snapshot,
79
- retain: @retain
79
+ retain: @retain,
80
+ sources: group.flat_map(&:sources)
80
81
  )
81
82
  end
82
83
  end
@@ -0,0 +1,114 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Leaves out the events of records that were outside the root's tree.
6
+ #
7
+ # A record found in the tree at one time in a range brings every version it
8
+ # saved in the range, including those it saved while it belonged elsewhere:
9
+ # a comment edited on another article before it moved to this one, or after
10
+ # it left a scope. Such a version changes nothing the root shows. As a
11
+ # boundary it would open a step of its own, and inside a transaction, where
12
+ # a change surfaces one event late, that step would take the credit for the
13
+ # root's own change.
14
+ #
15
+ # PT-AT reads associations as they were before a transaction, so a record
16
+ # is judged by two snapshots: the one at its transaction's first event, and
17
+ # the one after its last, which is the next event's or what the range
18
+ # closes on. A record in neither was outside the tree throughout.
19
+ #
20
+ # The root's own events are always kept, and so are the versions of a
21
+ # through's join rows, which a snapshot does not hold, and an event whose
22
+ # step is not reported, which only bounds one that is.
23
+ class ActivityTreeFilter
24
+ # `closing` is the snapshot after the last event: the current record's,
25
+ # or nil when nothing follows, as after the root's destruction.
26
+ #: (Array[ActivityEvent], reported: untyped, closing: RecordSnapshot?) -> void
27
+ def initialize(events, reported:, closing:)
28
+ @reported = reported
29
+ @closing = closing
30
+ @starts, @ends = spans(events)
31
+ @types = {} #: Hash[String, Array[String?]]
32
+ end
33
+
34
+ # Yields each event of the sequence with its snapshot, and whether to keep
35
+ # it, in order.
36
+ #: (untyped) { (ActivityEvent, RecordSnapshot?, bool) -> void } -> void
37
+ def call(sequence)
38
+ pairs = sequence.to_enum.to_a #: Array[[ActivityEvent, RecordSnapshot?]]
39
+ pairs.each_with_index do |(event, snapshot), index|
40
+ yield event, snapshot, keep?(event, index, pairs)
41
+ end
42
+ end
43
+
44
+ private
45
+
46
+ # @rbs @reported: untyped
47
+ # @rbs @closing: RecordSnapshot?
48
+ # @rbs @starts: Array[Integer]
49
+ # @rbs @ends: Array[Integer]
50
+ # @rbs @types: Hash[String, Array[String?]]
51
+
52
+ #: (ActivityEvent, Integer, Array[[ActivityEvent, RecordSnapshot?]]) -> bool
53
+ def keep?(event, index, pairs)
54
+ return true if event.root? || event.join? || !reported?(event)
55
+
56
+ position = @ends.fetch(index)
57
+ after = position < pairs.length ? pairs.fetch(position).last : @closing
58
+ holds?(pairs.fetch(@starts.fetch(index)).last, event) || holds?(after, event)
59
+ end
60
+
61
+ #: (ActivityEvent) -> bool
62
+ def reported?(event)
63
+ !@reported || @reported.call(event)
64
+ end
65
+
66
+ # Where each event's transaction starts, and the position just past its
67
+ # last event. Two transactions can interleave, so a transaction's events
68
+ # need not be adjacent.
69
+ #: (Array[ActivityEvent]) -> [Array[Integer], Array[Integer]]
70
+ def spans(events)
71
+ keys = transaction_keys(events)
72
+ first = {} #: Hash[Array[untyped] | Integer, Integer]
73
+ last = {} #: Hash[Array[untyped] | Integer, Integer]
74
+ keys.each_with_index do |key, index|
75
+ first[key] ||= index
76
+ last[key] = index
77
+ end
78
+ [keys.map { |key| first.fetch(key) }, keys.map { |key| last.fetch(key) + 1 }]
79
+ end
80
+
81
+ # A version saved outside a transaction is a transaction of its own,
82
+ # keyed by its position.
83
+ #: (Array[ActivityEvent]) -> Array[Array[untyped] | Integer]
84
+ def transaction_keys(events)
85
+ events.each_with_index.map do |event, index|
86
+ ActivityTransactionGroups.transaction_key(event.version) || index
87
+ end
88
+ end
89
+
90
+ #: (RecordSnapshot?, ActivityEvent) -> bool
91
+ def holds?(snapshot, event)
92
+ return false unless snapshot
93
+
94
+ version = event.version
95
+ types = types(version.item_type)
96
+ branches = event.branches #: Array[String]
97
+ branches.any? { |name| contains?(snapshot.associations.fetch(name), types, version.item_id) }
98
+ end
99
+
100
+ #: (AssociationSnapshot, Array[String?], untyped) -> bool
101
+ def contains?(association, types, id)
102
+ types.any? { |type| association.position(type, id) } || association.records.any? do |record|
103
+ record.associations.each_value.any? { |nested| contains?(nested, types, id) }
104
+ end
105
+ end
106
+
107
+ # A version names its record's base class, and a snapshot the record's
108
+ # own class, which may be any subclass of it.
109
+ #: (String) -> Array[String?]
110
+ def types(base_name)
111
+ @types[base_name] ||= [base_name, *Object.const_get(base_name).descendants.map(&:name)]
112
+ end
113
+ end
114
+ end
@@ -22,13 +22,15 @@ module PaperTrailDiff
22
22
  @registry = ActivityEventRegistry.new
23
23
  end
24
24
 
25
+ # A tie between version tables, or between ids that do not count up,
26
+ # raises rather than building a timeline in an arbitrary order.
25
27
  #: () -> Array[ActivityEvent]
26
28
  def call
27
29
  @registry.add(@root_versions)
28
30
  collect_tree(@record.class, [@record.id], @tree, path: '', branch: nil) unless @tree.empty?
29
- @registry.to_a.sort_by do |event|
30
- Support.chronological_version_key(event.version)
31
- end.freeze
31
+ events = @registry.to_a.sort_by { |event| Support.chronological_version_key(event.version) }
32
+ pair = Support.ambiguous_pair(events.map(&:version))
33
+ pair ? raise(AmbiguousVersionOrderError, Support.ambiguous_message(pair)) : events.freeze
32
34
  end
33
35
 
34
36
  private
@@ -92,7 +94,7 @@ module PaperTrailDiff
92
94
  # A through is always read with prepared history, which knows the
93
95
  # join row's state either side of each version.
94
96
  @registry.add(@prepared&.join_versions(group, reflection) || group.fetch(:versions),
95
- branch: branch)
97
+ branch: branch, join: true)
96
98
  source = reflection.source_reflection
97
99
  children = edge_groups(group, source, branch)
98
100
  merge_groups!(result, children)
@@ -141,7 +143,7 @@ module PaperTrailDiff
141
143
  return identity_groups(rows, reflection)
142
144
  end
143
145
  transaction_ids = parent_versions.filter_map do |version|
144
- version.transaction_id if version.respond_to?(:transaction_id)
146
+ VersionBoundary.transaction_id(version)
145
147
  end
146
148
  rows = parent_class.paper_trail.version_association_class.where(
147
149
  version_id: transaction_ids,