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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +501 -0
- data/QUICKSTART.md +21 -4
- data/README.md +59 -56
- data/docs/architecture.md +32 -11
- data/docs/performance.md +125 -391
- data/docs/reference.md +470 -117
- data/docs/testing.md +83 -7
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +18 -3
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
- data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +37 -6
- data/lib/paper_trail_diff/analysis_batch.rb +25 -31
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
- data/lib/paper_trail_diff/association_discovery.rb +9 -1
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +13 -4
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
- data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +86 -99
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +3 -1
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
- data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
- data/lib/paper_trail_diff/prepared_history.rb +15 -1
- data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
- data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
- data/lib/paper_trail_diff/read_snapshot.rb +77 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +157 -32
- data/lib/paper_trail_diff/scope_ranking.rb +23 -14
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/support.rb +29 -2
- data/lib/paper_trail_diff/time_range.rb +39 -16
- data/lib/paper_trail_diff/timeline_builder.rb +13 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +240 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_boundary.rb +41 -10
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +101 -57
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +3 -1
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
- data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/support.rbs +15 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +29 -26
- metadata +49 -11
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -63
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
- 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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
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
|
-
#
|
|
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
|
|
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
|
-
|
|
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 @
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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,
|
|
85
|
-
activity_steps(history,
|
|
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,
|
|
91
|
-
final
|
|
92
|
-
|
|
93
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
|
121
|
-
#
|
|
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,
|
|
131
|
+
#: (RootVersionPlan) -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
|
|
124
132
|
def empty_history(plan)
|
|
125
|
-
[plan,
|
|
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
|
-
|
|
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
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
-
|
|
196
|
-
|
|
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
|
-
|
|
357
|
+
include_step: ->(event) { @range.include?(event.version) },
|
|
358
|
+
view: @view,
|
|
359
|
+
closing: closing
|
|
203
360
|
).call
|
|
204
361
|
end
|
|
205
362
|
|
|
206
|
-
#
|
|
207
|
-
# the
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
#: () ->
|
|
223
|
-
def
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
|
@@ -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
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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,
|