paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -2,20 +2,18 @@
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: false, group: nil) # 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
- @from = range.from
19
17
  @to = range.to
20
18
  @range = range
21
19
  @tree = tree
@@ -24,7 +22,7 @@ module PaperTrailDiff
24
22
 
25
23
  #: () -> Array[ActivityStep]
26
24
  def build
27
- return time_builder.build if @range.time?
25
+ return window_steps if @range.time?
28
26
  return no_steps if @range.unresolved?
29
27
  return build_to_current if Endpoint.record?(@to)
30
28
 
@@ -32,29 +30,28 @@ module PaperTrailDiff
32
30
  build_between_versions
33
31
  end
34
32
 
35
- # Builds all three version-bounded views from one activity snapshot pass.
33
+ # Builds the endpoint diff, the root timeline, and the activity from one
34
+ # activity snapshot pass.
36
35
  #: () -> Analysis
37
36
  def analyze
38
- return time_builder.analyze if @range.time?
37
+ return analyze_window if @range.time?
39
38
  return Analysis.empty if @range.unresolved?
40
39
  return analyze_current if Endpoint.record?(@to)
41
40
 
42
41
  plan = @range.select_plan
43
- root_versions = plan.reconstruction_versions
44
- prepare_history(root_versions)
45
- events = collect_events(root_versions)
46
- build_analysis(plan, events, event_history(root_versions, events))
42
+ return Analysis.empty if plan.empty?
43
+
44
+ build_analysis(plan, version_history(plan.reconstruction_versions))
47
45
  end
48
46
 
49
47
  private
50
48
 
51
49
  # @rbs @record: untyped
52
- # @rbs @from: untyped
53
50
  # @rbs @to: untyped
54
51
  # @rbs @range: TimelineRange
55
52
  # @rbs @tree: AssociationTree
56
53
  # @rbs @snapshotter: untyped
57
- # @rbs @snapshots: bool
54
+ # @rbs @view: ActivityView
58
55
 
59
56
  #: () -> Array[ActivityStep]
60
57
  def no_steps
@@ -65,52 +62,74 @@ module PaperTrailDiff
65
62
  # Every boundary in the span, filtered out or not. A filter narrows where the
66
63
  # span starts and ends, but the sequence inside it stays complete: dropping
67
64
  # boundaries would fold the changes they carried into a neighbouring step and
68
- # credit them to whoever made that one.
65
+ # credit them to whoever made that one. A filter that keeps no version
66
+ # leaves no span, as it does for a checkpoint timeline.
69
67
  #: () -> Array[ActivityStep]
70
68
  def build_between_versions
71
- root_versions = @range.select_plan.reconstruction_versions
72
- prepare_history(root_versions)
73
- events = collect_events(root_versions)
74
- history = event_history(root_versions, events)
75
- activity_steps(history, events, destroyed_boundary(root_versions), nil)
69
+ plan = @range.select_plan
70
+ return no_steps if plan.empty?
71
+
72
+ root_versions = plan.reconstruction_versions
73
+ activity_steps(version_history(root_versions), destroyed_boundary(root_versions), nil)
74
+ end
75
+
76
+ # Activity from the first to the last of the root versions.
77
+ #: (Array[untyped]) -> ActivityHistory
78
+ def version_history(root_versions)
79
+ snapshots = prepare_history(root_versions)
80
+ events = collect_events(root_versions, snapshots, range_end: root_versions.last)
81
+ replay(root_versions, events, snapshots)
76
82
  end
77
83
 
78
84
  #: () -> Array[ActivityStep]
79
85
  def build_to_current
80
- _plan, events, history, snapshot, boundary = current_history
81
- activity_steps(history, events, boundary, snapshot)
86
+ _plan, history, snapshot, boundary = current_history
87
+ activity_steps(history, boundary, snapshot)
82
88
  end
83
89
 
84
90
  #: () -> Analysis
85
91
  def analyze_current
86
- plan, events, history, snapshot, boundary = current_history
87
- final = boundary ? snapshot : history.last_snapshot
88
- Analysis.new(
89
- diff: Engine.compare(history.first_snapshot, final),
90
- timeline: ActivityRootSteps.call(
91
- plan, history.root_snapshots, closing_snapshot: snapshot,
92
- captured_at: boundary&.recorded_at
93
- ),
94
- activity_timeline: activity_steps(history, events, boundary, snapshot),
95
- from_snapshot: history.first_snapshot, to_snapshot: final
96
- )
92
+ plan, history, snapshot, boundary = current_history
93
+ analysis(plan, history, final: boundary ? snapshot : history.last_snapshot,
94
+ steps: activity_steps(history, boundary, snapshot),
95
+ closing_snapshot: snapshot, captured_at: boundary&.recorded_at)
97
96
  end
98
97
 
99
98
  # The explicit live endpoint and a batch's live closing endpoint use the
100
99
  # same selected plan. A version filter can close earlier, on its successor.
101
- #: () -> [RootVersionPlan, Array[ActivityEvent], ActivityHistory, RecordSnapshot?, ActivityBoundary?]
100
+ #: () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
102
101
  def current_history
103
102
  validate_current_range!
104
103
  plan = @range.select_plan
105
- return [plan, [], ActivityHistory.empty, nil, nil] if plan.empty?
104
+ return empty_history(plan) if plan.empty?
106
105
 
107
106
  snapshot, captured_at = capture_current if plan.closing_record
107
+ history = history_until(plan, snapshot, captured_at)
108
+ boundary = current_boundary(captured_at) if plan.closing_record
109
+ [plan, history, snapshot, boundary]
110
+ end
111
+
112
+ # Events up to the instant the current record was read. A range that a
113
+ # version filter closes earlier ends at that version, with no snapshot.
114
+ #: (RootVersionPlan, RecordSnapshot?, untyped) -> ActivityHistory
115
+ def history_until(plan, snapshot, captured_at)
108
116
  versions = plan.reconstruction_versions
109
- prepare_history(versions, end_at: captured_at)
110
- events = collect_events(versions, range_end: captured_at || versions.last)
111
- history = event_history(versions, events, current: plan.closing_record)
112
- boundary = ActivityBoundary.current(@to, captured_at: captured_at) if plan.closing_record
113
- [plan, events, history, snapshot, boundary]
117
+ snapshots = prepare_history(versions, end_at: captured_at)
118
+ events = collect_events(versions, snapshots, range_end: captured_at || versions.last)
119
+ replay(versions, events, snapshots, current: plan.closing_record, closing: snapshot)
120
+ end
121
+
122
+ # Without a closing boundary nothing reads the closing pair, so its
123
+ # mutations cannot change an answer.
124
+ # mutant:disable
125
+ #: (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
126
+ def empty_history(plan)
127
+ [plan, ActivityHistory.empty, nil, nil]
128
+ end
129
+
130
+ #: (untyped) -> ActivityBoundary
131
+ def current_boundary(captured_at)
132
+ ActivityBoundary.current(@to, captured_at: captured_at, recorded: root_recorded)
114
133
  end
115
134
 
116
135
  #: () -> [RecordSnapshot?, untyped]
@@ -120,55 +139,25 @@ module PaperTrailDiff
120
139
 
121
140
  #: () -> void
122
141
  def validate_current_range!
123
- unless Endpoint.version?(@from)
142
+ unless Endpoint.version?(@range.from)
124
143
  raise InvalidTimelineRangeError, '`from` must be a root PaperTrail version'
125
144
  end
126
145
 
127
- Endpoint.validate_pair!(@from, @to)
128
- Endpoint.validate_pair!(@record, @to)
129
- AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
130
- end
131
-
132
- #: (Array[untyped], ?range_start: untyped, ?range_end: untyped) -> Array[ActivityEvent]
133
- def collect_events(
134
- root_versions,
135
- range_start: root_versions.first,
136
- range_end: root_versions.last
137
- )
138
- ActivityVersionCollector.new(
139
- @record,
140
- root_versions: root_versions,
141
- tree: @tree,
142
- traversal: AssociationTraversal.new(@tree),
143
- prepared: (@snapshotter.activity_index if @snapshotter.respond_to?(:activity_index)),
144
- range_start: range_start,
145
- range_end: range_end
146
- ).call
147
- end
148
-
149
- #: (Array[untyped], ?end_at: untyped) -> void
150
- def prepare_history(root_versions, end_at: nil)
151
- return unless @snapshotter.respond_to?(:prepare)
152
- return @snapshotter.prepare(@record, root_versions) unless end_at
153
-
154
- @snapshotter.prepare(@record, root_versions, end_at: end_at)
146
+ Endpoint.validate_pair!(@range.from, @to)
147
+ reject_live_habtm!
155
148
  end
156
149
 
157
150
  # Appends the transition into an explicit closing boundary, which is either
158
151
  # a requested current record or the absence a final root destroy leaves.
159
- #: (ActivityHistory, Array[ActivityEvent], ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
160
- def activity_steps(history, events, final_boundary, final_snapshot)
161
- steps = history.steps.dup
162
- previous_event = events.last
163
- previous_boundary = ActivityBoundary.from_version(previous_event.version) if previous_event
164
- if final_boundary && previous_boundary
165
- steps << ActivityStep.between(
166
- from_boundary: previous_boundary, to_boundary: final_boundary,
167
- from_snapshot: history.last_snapshot, to_snapshot: final_snapshot,
168
- retain: @retain
169
- )
170
- end
171
- group_steps(steps).freeze
152
+ # Either follows the root versions, which are themselves events, so the
153
+ # last boundary the history kept opens it.
154
+ #: (ActivityHistory, ActivityBoundary?, RecordSnapshot?) -> Array[ActivityStep]
155
+ def activity_steps(history, final_boundary, final_snapshot)
156
+ return present(history.steps) unless final_boundary
157
+
158
+ last_boundary = history.last_boundary #: ActivityBoundary
159
+ present(history.steps + [step_from_last(history, last_boundary, final_boundary,
160
+ final_snapshot)])
172
161
  end
173
162
 
174
163
  # A destroyed root has no later version, but its own event states that
@@ -176,47 +165,219 @@ module PaperTrailDiff
176
165
  #: (Array[untyped]) -> ActivityBoundary?
177
166
  def destroyed_boundary(root_versions)
178
167
  version = root_versions.last
179
- return unless version && version.event.to_s == 'destroy'
168
+ return unless version.event == 'destroy'
180
169
 
181
- ActivityBoundary.destroyed(version)
182
- end
183
-
184
- #: (Array[untyped], Array[ActivityEvent], ?current: untyped) -> ActivityHistory
185
- def event_history(root_versions, events, current: nil)
186
- ActivityHistoryBuilder.new(
187
- root_versions,
188
- events,
189
- @snapshotter,
190
- current: current,
191
- snapshots: @retain
192
- ).call
170
+ ActivityBoundary.destroyed(version, recorded: root_recorded)
193
171
  end
194
172
 
195
173
  # Only the activity view gains the closing removal. The endpoint diff and
196
174
  # the root timeline keep their `compare` and `timeline` semantics, under
197
175
  # which the state at a destroy version is the state before the deletion.
198
- #: (RootVersionPlan, Array[ActivityEvent], ActivityHistory) -> Analysis
199
- def build_analysis(plan, events, history)
200
- Analysis.new(
201
- diff: Engine.compare(history.first_snapshot, history.last_snapshot),
202
- timeline: ActivityRootSteps.call(plan, history.root_snapshots),
203
- activity_timeline: activity_steps(
204
- history, events, destroyed_boundary(plan.reconstruction_versions), nil
205
- ),
206
- from_snapshot: history.first_snapshot,
207
- to_snapshot: history.last_snapshot
176
+ #: (RootVersionPlan, ActivityHistory) -> Analysis
177
+ def build_analysis(plan, history)
178
+ steps = activity_steps(history, destroyed_boundary(plan.reconstruction_versions), nil)
179
+ analysis(plan, history, final: history.last_snapshot, steps: steps)
180
+ end
181
+
182
+ #: () -> Array[ActivityStep]
183
+ def window_steps
184
+ history, _plan, closing, = window_history
185
+ present(closing ? history.steps + [closing] : history.steps)
186
+ end
187
+
188
+ #: () -> Analysis
189
+ def analyze_window
190
+ history, plan, closing, closing_snapshot, captured_at = window_history
191
+ analysis(plan, history,
192
+ final: window_final_snapshot(history, closing, closing_snapshot),
193
+ steps: present(closing ? history.steps + [closing] : history.steps),
194
+ closing_snapshot: closing_snapshot, captured_at: captured_at)
195
+ end
196
+
197
+ # A window with a closing step ends at what closed it: the live row, or
198
+ # nothing after a destroy, where no live row is read. One that ends before
199
+ # a later event ends at the state that event found.
200
+ #: (ActivityHistory, ActivityStep?, RecordSnapshot?) -> RecordSnapshot?
201
+ def window_final_snapshot(history, closing, closing_snapshot)
202
+ closing ? closing_snapshot : history.last_snapshot
203
+ end
204
+
205
+ #: () -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
206
+ def window_history
207
+ plan = @range.select_plan(context_required: !@tree.empty?)
208
+ reject_live_habtm! if plan.closing_record
209
+ return empty_window(plan) if plan.empty? && !plan.closing_record
210
+
211
+ # A window closing on current state runs to the instant it is captured,
212
+ # not to the last root version, or descendants that moved after that
213
+ # version would be missing from a report that claims to reach now.
214
+ window_replay(plan, (Time.now.utc if plan.closing_record))
215
+ end
216
+
217
+ # Nothing reads a window's closing step, live snapshot, or capture time
218
+ # when it reported nothing, so mutations of those cannot change an answer.
219
+ # mutant:disable
220
+ #: (RootVersionPlan) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
221
+ def empty_window(plan)
222
+ [ActivityHistory.empty, plan, nil, nil, nil]
223
+ end
224
+
225
+ # A window with no selected event reports nothing. Any other has a
226
+ # boundary after its last one: the plan refuses a window that has no later
227
+ # version, ends on no destroy, and does not close on the live row.
228
+ #: (RootVersionPlan, untyped) -> [ActivityHistory, RootVersionPlan, ActivityStep?, RecordSnapshot?, untyped]
229
+ def window_replay(plan, captured_at)
230
+ versions = plan.reconstruction_versions
231
+ snapshots = prepare_history(versions, end_at: captured_at)
232
+ events = collect_events(versions, snapshots, range_end: captured_at || versions.last)
233
+ selected = selected_events(events, plan)
234
+ last = selected.last
235
+ return empty_window(plan) unless last
236
+
237
+ snapshot = window_live_snapshot(plan)
238
+ history = replay(versions, events, snapshots, current: plan.closing_record, closing: snapshot)
239
+ closing = window_closing(history, last, plan, captured_at, snapshot, events)
240
+ [history, plan, closing, snapshot, captured_at]
241
+ end
242
+
243
+ # One live read serves both the closing activity step and the endpoint the
244
+ # analysis reports, which would otherwise reconstruct the graph twice.
245
+ #: (RootVersionPlan) -> RecordSnapshot?
246
+ def window_live_snapshot(plan)
247
+ record = plan.closing_record
248
+ return unless record
249
+
250
+ @snapshotter.call(record, record)
251
+ end
252
+
253
+ # Root versions inside the window that the plan does not report are context
254
+ # rather than mutations: the version appended to reveal the last selected
255
+ # change, and anything a filter excluded but the replay still walks. Neither
256
+ # may be counted as a selected mutation. Descendant events are not filtered,
257
+ # so window membership is the whole test for them.
258
+ #: (Array[ActivityEvent], RootVersionPlan) -> Array[ActivityEvent]
259
+ def selected_events(events, plan)
260
+ events.select do |event|
261
+ @range.include?(event.version) && (!event.root? || plan.mutation?(event.version))
262
+ end
263
+ end
264
+
265
+ # A window either closes on the absence its final destruction leaves, or on
266
+ # current state when it reaches past everything recorded. Both are boundaries
267
+ # no version can supply.
268
+ #
269
+ # Everything recorded means on every requested path, not only the root's
270
+ # own versions. When an association changed after the window, its last
271
+ # step already ends at that change, at the state the window left; closing
272
+ # on current state would add the later change to a window it was not in.
273
+ #: (ActivityHistory, ActivityEvent, RootVersionPlan, untyped, RecordSnapshot?, Array[ActivityEvent]) -> ActivityStep?
274
+ def window_closing(history, event, plan, captured_at, snapshot, events) # rubocop:disable Metrics/ParameterLists
275
+ return window_destroyed_step(history, event) if terminal_destroy?(event)
276
+ return unless plan.closing_record
277
+ return if events.any? { |later| !@range.include?(later.version) }
278
+
279
+ window_current_step(history, plan.closing_record, captured_at, snapshot)
280
+ end
281
+
282
+ #: (ActivityHistory, ActivityEvent) -> ActivityStep
283
+ def window_destroyed_step(history, event)
284
+ version = event.version
285
+ ActivityStep.between(
286
+ from_boundary: ActivityBoundary.from_version(version, recorded: root_recorded),
287
+ to_boundary: ActivityBoundary.destroyed(version, recorded: root_recorded),
288
+ from_snapshot: history.root_snapshots.fetch(ActivityRootSteps.version_key(version)),
289
+ to_snapshot: nil, retain: @view.retain?
208
290
  )
209
291
  end
210
292
 
211
- #: () -> TimeActivityTimelineBuilder
212
- def time_builder
213
- TimeActivityTimelineBuilder.new(
293
+ # The last boundary reached is where current state is compared from, which
294
+ # is the final event rather than the final root version once descendants
295
+ # have moved since it. A selected event is a boundary the history kept.
296
+ #: (ActivityHistory, untyped, untyped, RecordSnapshot?) -> ActivityStep
297
+ def window_current_step(history, record, captured_at, snapshot)
298
+ previous = history.last_boundary #: ActivityBoundary
299
+ current = ActivityBoundary.current(record, captured_at: captured_at, recorded: root_recorded)
300
+ step_from_last(history, previous, current, snapshot)
301
+ end
302
+
303
+ #: (ActivityEvent) -> bool
304
+ def terminal_destroy?(event)
305
+ event.root? && event.version.event == 'destroy'
306
+ end
307
+
308
+ #: () -> void
309
+ def reject_live_habtm!
310
+ AssociationTraversal.new(@tree).reject_live_habtm_activity!(@record.class)
311
+ end
312
+
313
+ #: () -> Array[String]?
314
+ def root_recorded
315
+ @view.recorded_attributes(root: true)
316
+ end
317
+
318
+ # A window prepares from its start, explicit endpoints from their first
319
+ # version.
320
+ #: (Array[untyped], ?end_at: untyped) -> untyped
321
+ def prepare_history(root_versions, end_at: nil)
322
+ options = { start_at: @range.begin_time, end_at: end_at }.compact
323
+ @snapshotter.prepare(@record, root_versions, **options)
324
+ end
325
+
326
+ # A window collects from its start, explicit endpoints from their first
327
+ # version. Explicit endpoints also stop before the rest of the closing
328
+ # version's transaction (see ActivityTransactionGroups.before_closing); a
329
+ # window keeps every event it collected and reports only those inside it.
330
+ #: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
331
+ def collect_events(root_versions, snapshots, range_end:)
332
+ events = ActivityVersionCollector.new(
214
333
  @record,
215
- range: @range,
334
+ root_versions: root_versions,
216
335
  tree: @tree,
217
- snapshotter: @snapshotter,
218
- snapshots: @snapshots,
219
- group: @group
336
+ prepared: snapshots.activity_index,
337
+ range_start: @range.begin_time || root_versions.first,
338
+ range_end: range_end
339
+ ).call
340
+ @range.time? ? events : ActivityTransactionGroups.before_closing(events, range_end)
341
+ end
342
+
343
+ # Events after the last root version read the root from the live record
344
+ # when the range closes on it. Explicit endpoints report every step, as
345
+ # their range includes every version.
346
+ #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?closing: RecordSnapshot?) -> ActivityHistory
347
+ def replay(root_versions, events, snapshots, current: nil, closing: nil)
348
+ ActivityHistoryBuilder.new(
349
+ root_versions, events, snapshots,
350
+ current: current,
351
+ include_step: ->(event) { @range.include?(event.version) },
352
+ view: @view,
353
+ closing: closing
354
+ ).call
355
+ end
356
+
357
+ # The step from the last boundary the history reached to one that closes
358
+ # the range.
359
+ #: (ActivityHistory, ActivityBoundary, ActivityBoundary, RecordSnapshot?) -> ActivityStep
360
+ def step_from_last(history, last_boundary, closing_boundary, closing_snapshot)
361
+ ActivityStep.between(
362
+ from_boundary: last_boundary, to_boundary: closing_boundary,
363
+ from_snapshot: history.last_event_snapshot, to_snapshot: closing_snapshot,
364
+ retain: @view.retain?
365
+ )
366
+ end
367
+
368
+ #: (Array[ActivityStep]) -> Array[ActivityStep]
369
+ def present(steps)
370
+ @view.present(steps).freeze
371
+ end
372
+
373
+ #: (RootVersionPlan, ActivityHistory, final: RecordSnapshot?, steps: Array[ActivityStep], ?closing_snapshot: RecordSnapshot?, ?captured_at: untyped) -> Analysis
374
+ def analysis(plan, history, final:, steps:, **closing)
375
+ Analysis.new(
376
+ diff: Engine.compare(history.first_snapshot, final),
377
+ timeline: ActivityRootSteps.call(plan, history.root_snapshots, **closing),
378
+ activity_timeline: steps,
379
+ from_snapshot: history.first_snapshot,
380
+ to_snapshot: final
220
381
  )
221
382
  end
222
383
  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