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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +630 -0
- data/QUICKSTART.md +30 -10
- data/README.md +91 -13
- data/docs/architecture.md +62 -18
- data/docs/performance.md +116 -298
- data/docs/reference.md +554 -102
- data/docs/testing.md +93 -14
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
- 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 +11 -1
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
- data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +32 -5
- data/lib/paper_trail_diff/activity_relationship.rb +12 -0
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
- data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
- 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 +37 -24
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +13 -1
- data/lib/paper_trail_diff/analysis_batch.rb +24 -30
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
- data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
- data/lib/paper_trail_diff/association_discovery.rb +14 -11
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +180 -47
- 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 +12 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
- 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/comparison_batch.rb +37 -10
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
- data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +105 -102
- data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +5 -2
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
- data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
- data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
- data/lib/paper_trail_diff/prepared_history.rb +70 -53
- data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
- data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
- data/lib/paper_trail_diff/recorded_changes.rb +83 -0
- data/lib/paper_trail_diff/recorded_class.rb +53 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +386 -0
- data/lib/paper_trail_diff/scope_ranking.rb +206 -0
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
- data/lib/paper_trail_diff/support.rb +38 -6
- data/lib/paper_trail_diff/time_range.rb +37 -18
- data/lib/paper_trail_diff/time_version_range.rb +5 -5
- data/lib/paper_trail_diff/timeline_builder.rb +7 -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 +181 -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_association_candidate_scope.rb +13 -3
- data/lib/paper_trail_diff/version_boundary.rb +37 -8
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_range.rb +8 -15
- data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +126 -55
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
- 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_activity_edge.rbs +148 -0
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
- 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/comparison_batch.rbs +22 -4
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +5 -2
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
- data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
- data/sig/generated/paper_trail_diff/support.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
- data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +94 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
- data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +47 -25
- metadata +62 -10
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -55
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
- 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
|
-
|
|
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
|
-
@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
|
|
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
|
|
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
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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 @
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
activity_steps(
|
|
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,
|
|
81
|
-
activity_steps(history,
|
|
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,
|
|
87
|
-
final
|
|
88
|
-
|
|
89
|
-
|
|
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,
|
|
100
|
+
#: () -> [RootVersionPlan, ActivityHistory, RecordSnapshot?, ActivityBoundary?]
|
|
102
101
|
def current_history
|
|
103
102
|
validate_current_range!
|
|
104
103
|
plan = @range.select_plan
|
|
105
|
-
return
|
|
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
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
-
|
|
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
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
|
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,
|
|
199
|
-
def build_analysis(plan,
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
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
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
|
|
334
|
+
root_versions: root_versions,
|
|
216
335
|
tree: @tree,
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
|
@@ -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
|