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
|
@@ -5,22 +5,22 @@ module PaperTrailDiff
|
|
|
5
5
|
# Builds one root's Analysis inside a batch, from versions the batch already
|
|
6
6
|
# selected and history it already prepared.
|
|
7
7
|
class BatchedRootAnalyzer
|
|
8
|
-
#: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool,
|
|
9
|
-
def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, within: nil
|
|
8
|
+
#: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
|
|
9
|
+
def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, view:, within: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
|
|
10
10
|
@tree = tree
|
|
11
11
|
@timeline_snapshotter = timeline_snapshotter
|
|
12
12
|
@activity_snapshotter = activity_snapshotter
|
|
13
13
|
@preparer = preparer
|
|
14
14
|
@activity = activity
|
|
15
|
+
@view = view
|
|
15
16
|
@within = within
|
|
16
|
-
@snapshots = snapshots
|
|
17
|
-
@group = group
|
|
18
17
|
end
|
|
19
18
|
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
# `window` is the root's window as the batch moved it to transaction edges.
|
|
20
|
+
#: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
|
|
21
|
+
def call(record, plan, window = nil)
|
|
22
22
|
@preparer.call(record.class, historical: true)
|
|
23
|
-
return activity_analysis(record, plan) if @activity
|
|
23
|
+
return activity_analysis(record, plan, window) if @activity
|
|
24
24
|
|
|
25
25
|
TimelineBuilder.new(
|
|
26
26
|
record,
|
|
@@ -40,19 +40,17 @@ module PaperTrailDiff
|
|
|
40
40
|
# @rbs @preparer: untyped
|
|
41
41
|
# @rbs @activity: bool
|
|
42
42
|
# @rbs @within: untyped
|
|
43
|
-
# @rbs @
|
|
44
|
-
# @rbs @group: Symbol?
|
|
43
|
+
# @rbs @view: ActivityView
|
|
45
44
|
|
|
46
|
-
#: (untyped, RootVersionPlan) -> Analysis
|
|
47
|
-
def activity_analysis(record, plan)
|
|
45
|
+
#: (untyped, RootVersionPlan, TimeRange?) -> Analysis
|
|
46
|
+
def activity_analysis(record, plan, window)
|
|
48
47
|
range = TimelineRange.new(
|
|
49
48
|
record, from: (@within ? nil : plan.versions.first),
|
|
50
49
|
to: (@within ? nil : plan.closing_record || plan.versions.last),
|
|
51
|
-
within: @within, plan: plan
|
|
50
|
+
within: (window || @within if @within), plan: plan
|
|
52
51
|
)
|
|
53
52
|
ActivityTimelineBuilder.new(
|
|
54
|
-
record, range: range, tree: @tree, snapshotter: @activity_snapshotter,
|
|
55
|
-
snapshots: @snapshots, group: @group
|
|
53
|
+
record, range: range, tree: @tree, snapshotter: @activity_snapshotter, view: @view
|
|
56
54
|
).analyze
|
|
57
55
|
end
|
|
58
56
|
end
|
|
@@ -6,10 +6,13 @@ module PaperTrailDiff
|
|
|
6
6
|
# queries. Only the range forms that mean the same thing for every root are
|
|
7
7
|
# supported: a shared wall-clock window, or each root's own whole history.
|
|
8
8
|
class BatchedRootVersions
|
|
9
|
-
#: (Array[untyped], time_range: TimeRange?,
|
|
10
|
-
def initialize(
|
|
11
|
-
|
|
9
|
+
#: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
|
|
10
|
+
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
11
|
+
records, time_range:, version_scope:, live_endpoints:, context_required:, windows:
|
|
12
|
+
)
|
|
12
13
|
@records = records
|
|
14
|
+
# Roots whose window moved to a transaction's start, by identity.
|
|
15
|
+
@windows = windows
|
|
13
16
|
# An activity view needs a root to reconstruct from even in a window with
|
|
14
17
|
# no root version, exactly as a single-record activity timeline does.
|
|
15
18
|
@context_required = context_required
|
|
@@ -21,8 +24,6 @@ module PaperTrailDiff
|
|
|
21
24
|
# Returns a plan per record identity.
|
|
22
25
|
#: () -> Hash[Array[String], RootVersionPlan]
|
|
23
26
|
def call
|
|
24
|
-
return {} if @records.empty?
|
|
25
|
-
|
|
26
27
|
selected = {} #: Hash[Array[String], RootVersionPlan]
|
|
27
28
|
@records.group_by(&:class).each do |model_class, records|
|
|
28
29
|
select_model(model_class, records, selected)
|
|
@@ -37,33 +38,55 @@ module PaperTrailDiff
|
|
|
37
38
|
# @rbs @version_scope: untyped
|
|
38
39
|
# @rbs @live_endpoints: Hash[Array[String], untyped]?
|
|
39
40
|
# @rbs @context_required: bool
|
|
41
|
+
# @rbs @windows: Hash[Array[String], TimeRange]
|
|
40
42
|
|
|
41
43
|
#: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
|
|
42
44
|
def select_model(model_class, records, selected)
|
|
43
|
-
|
|
44
|
-
in_range, chosen, trailing = model_versions(model_class, ids)
|
|
45
|
+
in_range, chosen, trailing = model_versions(model_class, records)
|
|
45
46
|
records.each do |record|
|
|
46
|
-
key = identity(
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
live_endpoint(key, record)
|
|
50
|
-
)
|
|
47
|
+
key = Endpoint.identity(record)
|
|
48
|
+
own = own_window(key, record.id.to_s, in_range, trailing)
|
|
49
|
+
selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
|
|
51
50
|
end
|
|
52
51
|
end
|
|
53
52
|
|
|
53
|
+
# Moved windows only start and end earlier, so the versions read for the
|
|
54
|
+
# widest of them hold each root's own, and the first left past a moved end.
|
|
55
|
+
#: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
|
|
56
|
+
def own_window(key, id, in_range, trailing)
|
|
57
|
+
loaded = in_range.fetch(id, [])
|
|
58
|
+
return [loaded, trailing[id]] if @windows.empty?
|
|
59
|
+
|
|
60
|
+
# A batch moves windows only when it has one, so this is never nil.
|
|
61
|
+
window = @windows.fetch(key) { @time_range } #: untyped
|
|
62
|
+
own, rest = loaded.partition { |version| window.include?(version.created_at) }
|
|
63
|
+
[own, rest.find { |version| version.created_at >= window.end_time } || trailing[id]]
|
|
64
|
+
end
|
|
65
|
+
|
|
54
66
|
#: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
|
|
55
|
-
def model_versions(model_class,
|
|
67
|
+
def model_versions(model_class, records)
|
|
56
68
|
range = @time_range
|
|
57
69
|
empty = {} #: Hash[String, untyped]
|
|
70
|
+
widest = widest_range(records)
|
|
58
71
|
[
|
|
59
|
-
grouped_versions(model_class,
|
|
60
|
-
chosen_version_ids(model_class,
|
|
61
|
-
range ? trailing_versions(model_class,
|
|
72
|
+
grouped_versions(model_class, records, widest),
|
|
73
|
+
chosen_version_ids(model_class, records, widest),
|
|
74
|
+
range ? trailing_versions(model_class, records, range) : empty
|
|
62
75
|
]
|
|
63
76
|
end
|
|
64
77
|
|
|
65
|
-
#: (Array[untyped]
|
|
66
|
-
def
|
|
78
|
+
#: (Array[untyped]) -> TimeRange?
|
|
79
|
+
def widest_range(records)
|
|
80
|
+
range = @time_range
|
|
81
|
+
return unless range
|
|
82
|
+
|
|
83
|
+
moved = records.filter_map { |record| @windows[Endpoint.identity(record)]&.begin_time }
|
|
84
|
+
start = [range.begin_time, *moved].min
|
|
85
|
+
TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
#: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
|
|
89
|
+
def versions_for(in_range, after_range, chosen, live_endpoint)
|
|
67
90
|
RootVersionSelection.new(
|
|
68
91
|
in_range: in_range,
|
|
69
92
|
selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
|
|
@@ -89,48 +112,31 @@ module PaperTrailDiff
|
|
|
89
112
|
# One extra query names the selected mutations without discarding the
|
|
90
113
|
# unfiltered versions the successor lookup still needs.
|
|
91
114
|
#: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
|
|
92
|
-
def chosen_version_ids(model_class,
|
|
93
|
-
|
|
94
|
-
return unless scope
|
|
95
|
-
|
|
96
|
-
# A narrowed relation is the expected return. Active Support also gives
|
|
97
|
-
# `pluck` to plain enumerables, so an array of versions works too.
|
|
98
|
-
filtered = scope.call(range_scope(model_class, ids, range))
|
|
99
|
-
Set.new(filtered.pluck(:id))
|
|
115
|
+
def chosen_version_ids(model_class, records, range)
|
|
116
|
+
VersionScopeFilter.new(@version_scope).chosen_ids(range_scope(model_class, records, range))
|
|
100
117
|
end
|
|
101
118
|
|
|
102
119
|
#: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
|
|
103
|
-
def grouped_versions(model_class,
|
|
104
|
-
|
|
120
|
+
def grouped_versions(model_class, records, range)
|
|
121
|
+
VersionQuery.chronological(range_scope(model_class, records, range))
|
|
122
|
+
.group_by { |version| version.item_id.to_s }
|
|
105
123
|
end
|
|
106
124
|
|
|
107
125
|
#: (untyped, Array[untyped], TimeRange?) -> untyped
|
|
108
|
-
def range_scope(model_class,
|
|
109
|
-
scope = base_scope(model_class,
|
|
126
|
+
def range_scope(model_class, records, range)
|
|
127
|
+
scope = base_scope(model_class, records)
|
|
110
128
|
range ? range.scope(scope) : scope
|
|
111
129
|
end
|
|
112
130
|
|
|
113
131
|
#: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
|
|
114
|
-
def trailing_versions(model_class,
|
|
115
|
-
range.first_trailing_versions(base_scope(model_class,
|
|
132
|
+
def trailing_versions(model_class, records, range)
|
|
133
|
+
range.first_trailing_versions(base_scope(model_class, records))
|
|
116
134
|
end
|
|
117
135
|
|
|
118
136
|
#: (untyped, Array[untyped]) -> untyped
|
|
119
|
-
def base_scope(model_class,
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
item_id: ids
|
|
123
|
-
)
|
|
124
|
-
end
|
|
125
|
-
|
|
126
|
-
#: (untyped) -> Array[untyped]
|
|
127
|
-
def ordered(relation)
|
|
128
|
-
VersionQuery.chronological(relation).to_a
|
|
129
|
-
end
|
|
130
|
-
|
|
131
|
-
#: (untyped, untyped) -> Array[String]
|
|
132
|
-
def identity(model_class, id)
|
|
133
|
-
[model_class.base_class.name.to_s, id.to_s]
|
|
137
|
+
def base_scope(model_class, records)
|
|
138
|
+
# Active Record reads each record's id.
|
|
139
|
+
VersionQuery.for_items(model_class, records)
|
|
134
140
|
end
|
|
135
141
|
end
|
|
136
142
|
end
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# One change from an activity step, flat enough for a history table or an
|
|
6
|
+
# export: a field that changed, or a record that appeared or disappeared,
|
|
7
|
+
# with the event the step attributes it to.
|
|
8
|
+
class ChangeRow
|
|
9
|
+
attr_reader :change #: Symbol
|
|
10
|
+
attr_reader :association_path #: Array[String]
|
|
11
|
+
attr_reader :association_kind #: Symbol?
|
|
12
|
+
# The record the row is about, or nil for the root itself.
|
|
13
|
+
attr_reader :record #: RecordReference?
|
|
14
|
+
# The field the row is about, or nil for a row about a whole record.
|
|
15
|
+
attr_reader :attribute #: String?
|
|
16
|
+
attr_reader :from #: untyped
|
|
17
|
+
attr_reader :to #: untyped
|
|
18
|
+
# The step's source boundary: for a transaction group, its first event.
|
|
19
|
+
attr_reader :source #: ActivityBoundary
|
|
20
|
+
|
|
21
|
+
#: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
|
|
22
|
+
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
23
|
+
change:, association_path:, association_kind:, record:, attribute:, from:, to:, source:
|
|
24
|
+
)
|
|
25
|
+
@change = change
|
|
26
|
+
@association_path = association_path
|
|
27
|
+
@association_kind = association_kind
|
|
28
|
+
@record = record
|
|
29
|
+
@attribute = attribute
|
|
30
|
+
@from = from
|
|
31
|
+
@to = to
|
|
32
|
+
@source = source
|
|
33
|
+
freeze
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# The source's identifying fields sit beside the change rather than nested,
|
|
37
|
+
# so the hash is one row of a table as it stands.
|
|
38
|
+
#: () -> Hash[Symbol, untyped]
|
|
39
|
+
def to_h
|
|
40
|
+
{
|
|
41
|
+
change: change, association_path: association_path, association_kind: association_kind,
|
|
42
|
+
record: record&.to_h, attribute: attribute,
|
|
43
|
+
from: Support.serialize(from), to: Support.serialize(to)
|
|
44
|
+
}.merge(source_fields)
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
private
|
|
48
|
+
|
|
49
|
+
#: () -> Hash[Symbol, untyped]
|
|
50
|
+
def source_fields
|
|
51
|
+
{ version_id: source.version_id, event: source.event, whodunnit: source.whodunnit,
|
|
52
|
+
recorded_at: source.recorded_at, transaction_id: source.transaction_id }
|
|
53
|
+
end
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# Flattens one step's diff into change rows, in the diff's walking order.
|
|
57
|
+
#
|
|
58
|
+
# A row is about one record. An edited field is `:changed`. A record that
|
|
59
|
+
# appeared or disappeared is one `:added` or `:removed` row, followed by a
|
|
60
|
+
# row for each of its fields and for each record it holds, so a table can
|
|
61
|
+
# list a new comment's body without a second walker. That covers a record
|
|
62
|
+
# joining or leaving a collection, a to-one target set, cleared or replaced
|
|
63
|
+
# (the old target removed, then the new one added), and the root's own
|
|
64
|
+
# creation or deletion.
|
|
65
|
+
#
|
|
66
|
+
# Two kinds of entry add nothing a row would show. One that only groups
|
|
67
|
+
# others (an edited record, an association, a relationship) is left out,
|
|
68
|
+
# because the rows under it name the same record. A blank field of an added
|
|
69
|
+
# or removed record is left out too, because the record's own row already
|
|
70
|
+
# says it appeared or disappeared.
|
|
71
|
+
class ChangeRows
|
|
72
|
+
RECORD_ENTRIES = %i[record_added record_removed record_included].freeze
|
|
73
|
+
private_constant :RECORD_ENTRIES
|
|
74
|
+
|
|
75
|
+
#: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
|
|
76
|
+
def self.call(diff, source:)
|
|
77
|
+
new(source).call(diff)
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
#: (ActivityBoundary) -> void
|
|
81
|
+
def initialize(source)
|
|
82
|
+
@source = source
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
#: (Diff) -> Array[ChangeRow]
|
|
86
|
+
def call(diff)
|
|
87
|
+
rows = [] #: Array[ChangeRow]
|
|
88
|
+
diff.each_entry do |entry|
|
|
89
|
+
row = row_for(entry)
|
|
90
|
+
rows << row if row
|
|
91
|
+
end
|
|
92
|
+
rows.freeze
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
private
|
|
96
|
+
|
|
97
|
+
# @rbs @source: ActivityBoundary
|
|
98
|
+
|
|
99
|
+
#: (TraversalEntry) -> ChangeRow?
|
|
100
|
+
def row_for(entry)
|
|
101
|
+
return changed_row(entry) if entry.kind == :attribute_changed
|
|
102
|
+
return presence_row(entry, nil) if RECORD_ENTRIES.include?(entry.kind)
|
|
103
|
+
return unless entry.kind == :attribute_included && !entry.value.nil?
|
|
104
|
+
|
|
105
|
+
presence_row(entry, entry.attribute)
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
#: (TraversalEntry) -> ChangeRow
|
|
109
|
+
def changed_row(entry)
|
|
110
|
+
value = entry.value #: ValueChange
|
|
111
|
+
row(entry, :changed, entry.attribute, value.from, value.to)
|
|
112
|
+
end
|
|
113
|
+
|
|
114
|
+
# An added record's state is the after side and a removed one's the before
|
|
115
|
+
# side, so a field's value goes on the side that has it.
|
|
116
|
+
#: (TraversalEntry, String?) -> ChangeRow
|
|
117
|
+
def presence_row(entry, attribute)
|
|
118
|
+
value = attribute ? entry.value : nil
|
|
119
|
+
return row(entry, :added, attribute, nil, value) if entry.state == :after
|
|
120
|
+
|
|
121
|
+
row(entry, :removed, attribute, value, nil)
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
#: (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
|
|
125
|
+
def row(entry, change, attribute, from, to)
|
|
126
|
+
ChangeRow.new(
|
|
127
|
+
change: change, association_path: entry.association_path,
|
|
128
|
+
association_kind: entry.association_kind, record: entry.record,
|
|
129
|
+
attribute: attribute, from: from, to: to, source: @source
|
|
130
|
+
)
|
|
131
|
+
end
|
|
132
|
+
end
|
|
133
|
+
end
|
|
@@ -3,6 +3,8 @@
|
|
|
3
3
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Compares collection snapshots with a low-allocation path for stable membership.
|
|
6
|
+
# Snapshots hold their records in type and ID order, so results follow it
|
|
7
|
+
# without sorting here.
|
|
6
8
|
class CollectionComparator
|
|
7
9
|
#: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
|
|
8
10
|
def initialize(from_association, to_association, record_comparer:)
|
|
@@ -50,9 +52,7 @@ module PaperTrailDiff
|
|
|
50
52
|
pairs = aligned_changed_pairs
|
|
51
53
|
return unless pairs
|
|
52
54
|
|
|
53
|
-
pairs.
|
|
54
|
-
@record_comparer.call(pair.fetch(0), pair.fetch(1))
|
|
55
|
-
end
|
|
55
|
+
pairs.filter_map { |pair| @record_comparer.call(pair.fetch(0), pair.fetch(1)) }
|
|
56
56
|
end
|
|
57
57
|
|
|
58
58
|
#: () -> Array[[RecordSnapshot, RecordSnapshot]]?
|
|
@@ -105,13 +105,12 @@ module PaperTrailDiff
|
|
|
105
105
|
|
|
106
106
|
#: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
|
|
107
107
|
def records_missing_from(records, other_records)
|
|
108
|
-
|
|
109
|
-
identities.map { |identity| records.fetch(identity) }
|
|
108
|
+
(records.keys - other_records.keys).map { |identity| records.fetch(identity) }
|
|
110
109
|
end
|
|
111
110
|
|
|
112
111
|
#: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
|
|
113
112
|
def changed_records(from_records, to_records)
|
|
114
|
-
|
|
113
|
+
(from_records.keys & to_records.keys).filter_map do |identity|
|
|
115
114
|
from_record = from_records.fetch(identity)
|
|
116
115
|
to_record = to_records.fetch(identity)
|
|
117
116
|
next if from_record.equal?(to_record)
|
|
@@ -132,32 +131,6 @@ module PaperTrailDiff
|
|
|
132
131
|
index
|
|
133
132
|
end
|
|
134
133
|
|
|
135
|
-
#: (Array[identity]) -> Array[identity]
|
|
136
|
-
def sorted_identities(identities)
|
|
137
|
-
identities.sort_by { |identity| sortable_identity(identity) }
|
|
138
|
-
end
|
|
139
|
-
|
|
140
|
-
# Identities sort by type first so that mixed id types stay comparable, then
|
|
141
|
-
# naturally within one type. Ordering by the printed form instead would put
|
|
142
|
-
# id 10 before id 2, which is deterministic but reads as unsorted wherever a
|
|
143
|
-
# result is rendered.
|
|
144
|
-
#: (identity) -> Array[untyped]
|
|
145
|
-
def sortable_identity(identity)
|
|
146
|
-
[identity.fetch(0), sortable_id(identity.fetch(1))]
|
|
147
|
-
end
|
|
148
|
-
|
|
149
|
-
# Only the order of the group numbers matters, so moving the lowest one
|
|
150
|
-
# down or the highest one up changes nothing; the spec checks the order.
|
|
151
|
-
# mutant:disable
|
|
152
|
-
#: (untyped) -> Array[untyped]
|
|
153
|
-
def sortable_id(id)
|
|
154
|
-
case id
|
|
155
|
-
when Numeric then [0, id]
|
|
156
|
-
when String, Symbol then [1, id.to_s]
|
|
157
|
-
else [2, id.inspect]
|
|
158
|
-
end
|
|
159
|
-
end
|
|
160
|
-
|
|
161
134
|
#: (identity) -> void
|
|
162
135
|
def raise_duplicate_identity!(identity)
|
|
163
136
|
raise ArgumentError, "duplicate record identity: #{identity}"
|
|
@@ -4,12 +4,16 @@
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Validates and executes independent comparisons with shared live endpoint loading.
|
|
6
6
|
class ComparisonBatch
|
|
7
|
-
|
|
7
|
+
# `history_preparer` prepares roots that have a live endpoint to collect a
|
|
8
|
+
# graph from; `version_history_preparer` prepares roots compared only
|
|
9
|
+
# between versions.
|
|
10
|
+
#: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, version_history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
|
|
8
11
|
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
9
12
|
comparisons,
|
|
10
13
|
live_loader:,
|
|
11
14
|
preparer:,
|
|
12
15
|
history_preparer:,
|
|
16
|
+
version_history_preparer:,
|
|
13
17
|
historical_snapshotter:,
|
|
14
18
|
live_normalizer:
|
|
15
19
|
)
|
|
@@ -17,6 +21,7 @@ module PaperTrailDiff
|
|
|
17
21
|
@live_loader = live_loader
|
|
18
22
|
@preparer = preparer
|
|
19
23
|
@history_preparer = history_preparer
|
|
24
|
+
@version_history_preparer = version_history_preparer
|
|
20
25
|
@historical_snapshotter = historical_snapshotter
|
|
21
26
|
@live_normalizer = live_normalizer
|
|
22
27
|
end
|
|
@@ -35,6 +40,7 @@ module PaperTrailDiff
|
|
|
35
40
|
# @rbs @live_loader: untyped
|
|
36
41
|
# @rbs @preparer: untyped
|
|
37
42
|
# @rbs @history_preparer: untyped
|
|
43
|
+
# @rbs @version_history_preparer: untyped
|
|
38
44
|
# @rbs @historical_snapshotter: untyped
|
|
39
45
|
# @rbs @live_normalizer: untyped
|
|
40
46
|
|
|
@@ -97,20 +103,41 @@ module PaperTrailDiff
|
|
|
97
103
|
|
|
98
104
|
#: (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
|
|
99
105
|
def prepare_historical_batches!(pairs, live_records)
|
|
100
|
-
|
|
101
|
-
Endpoint.
|
|
106
|
+
loaded, unloaded = historical_versions(pairs).partition do |version|
|
|
107
|
+
live_records.key?(Endpoint.identity(version))
|
|
102
108
|
end
|
|
103
|
-
|
|
109
|
+
loaded.group_by { |version| RecordedClass.for(version) }.each_value do |versions|
|
|
104
110
|
records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }.uniq
|
|
105
111
|
@history_preparer.call(records, versions)
|
|
106
112
|
end
|
|
113
|
+
prepare_version_roots!(unloaded)
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
# A root compared only between versions has no live endpoint, and its row
|
|
117
|
+
# may be gone. Without prepared history, PT-AT finds a has_many's children
|
|
118
|
+
# by the keys each version recorded after its change, so it misses a child
|
|
119
|
+
# that later moved to another owner. Such roots are prepared from identity
|
|
120
|
+
# alone, like deleted ones. Their history still reads the live rows it
|
|
121
|
+
# needs: a record's current row is its state after its last version.
|
|
122
|
+
#: (Array[untyped]) -> void
|
|
123
|
+
def prepare_version_roots!(versions)
|
|
124
|
+
versions.group_by { |version| RecordedClass.for(version) }.each do |model, group|
|
|
125
|
+
ids = group.map(&:item_id).uniq(&:to_s)
|
|
126
|
+
@version_history_preparer.call(ids.map { |id| historical_root(model, id) }, group)
|
|
127
|
+
end
|
|
107
128
|
end
|
|
108
129
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
130
|
+
# The record supplies identity and model metadata only.
|
|
131
|
+
#: (untyped, untyped) -> untyped
|
|
132
|
+
def historical_root(model, id)
|
|
133
|
+
record = model.new
|
|
134
|
+
record[model.primary_key] = id
|
|
135
|
+
record
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
#: (Array[[untyped, untyped]]) -> Array[untyped]
|
|
139
|
+
def historical_versions(pairs)
|
|
140
|
+
selected = pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }
|
|
114
141
|
selected.uniq { |version| [version.class.name, version.id] }
|
|
115
142
|
end
|
|
116
143
|
|
|
@@ -167,7 +194,7 @@ module PaperTrailDiff
|
|
|
167
194
|
requirements = {} #: Hash[untyped, bool]
|
|
168
195
|
pairs.flatten.each_with_object(requirements) do |endpoint, collected|
|
|
169
196
|
historical = Endpoint.version?(endpoint)
|
|
170
|
-
model_class = historical ?
|
|
197
|
+
model_class = historical ? RecordedClass.for(endpoint) : endpoint.class
|
|
171
198
|
collected[model_class] = collected.fetch(model_class, false) || historical
|
|
172
199
|
end
|
|
173
200
|
end
|
|
@@ -7,19 +7,40 @@ module PaperTrailDiff
|
|
|
7
7
|
attr_reader :children #: Hash[String, AssociationTree]
|
|
8
8
|
|
|
9
9
|
class << self
|
|
10
|
+
# Takes what `includes` takes: a name, a dotted path, a hash of names to
|
|
11
|
+
# what to include below them, or an array of any of these.
|
|
10
12
|
#: (untyped) -> AssociationTree
|
|
11
13
|
def build(values)
|
|
12
|
-
unless valid_values?(values)
|
|
13
|
-
raise ConfigurationError, 'associations: must be an array of strings or symbols'
|
|
14
|
-
end
|
|
15
|
-
|
|
16
14
|
tree = {} #: Hash[String, untyped]
|
|
17
|
-
values.each { |
|
|
15
|
+
paths(values, nil).each { |path| add_path(tree, path) }
|
|
18
16
|
from_hash(tree)
|
|
19
17
|
end
|
|
20
18
|
|
|
21
19
|
private
|
|
22
20
|
|
|
21
|
+
#: (untyped, String?) -> Array[String]
|
|
22
|
+
def paths(value, prefix)
|
|
23
|
+
case value
|
|
24
|
+
when String, Symbol then [joined(prefix, value)]
|
|
25
|
+
when Array then value.flat_map { |item| paths(item, prefix) }
|
|
26
|
+
when Hash then value.flat_map { |name, nested| nested_paths(name, nested, prefix) }
|
|
27
|
+
else
|
|
28
|
+
raise ConfigurationError,
|
|
29
|
+
'associations: must be names, dotted paths, hashes of them, or arrays of these'
|
|
30
|
+
end
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# `{ comments: :replies }` names comments as well as their replies.
|
|
34
|
+
#: (untyped, untyped, String?) -> Array[String]
|
|
35
|
+
def nested_paths(name, nested, prefix)
|
|
36
|
+
paths(name, prefix).flat_map { |path| [path, *paths(nested, path)] }
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
#: (String?, String | Symbol) -> String
|
|
40
|
+
def joined(prefix, name)
|
|
41
|
+
prefix ? "#{prefix}.#{name}" : name.to_s
|
|
42
|
+
end
|
|
43
|
+
|
|
23
44
|
#: (Hash[String, untyped], String) -> void
|
|
24
45
|
def add_path(tree, path)
|
|
25
46
|
segments = path.split('.', -1)
|
|
@@ -39,13 +60,6 @@ module PaperTrailDiff
|
|
|
39
60
|
end
|
|
40
61
|
new(children)
|
|
41
62
|
end
|
|
42
|
-
|
|
43
|
-
#: (untyped) -> bool
|
|
44
|
-
def valid_values?(values)
|
|
45
|
-
values.is_a?(Array) && values.all? do |value|
|
|
46
|
-
value.is_a?(String) || value.is_a?(Symbol)
|
|
47
|
-
end
|
|
48
|
-
end
|
|
49
63
|
end
|
|
50
64
|
|
|
51
65
|
#: (Hash[String, AssociationTree]) -> void
|
|
@@ -166,5 +180,14 @@ module PaperTrailDiff
|
|
|
166
180
|
external_path = path.empty? ? ROOT_PATH : path
|
|
167
181
|
(all + paths.fetch(external_path, [])).uniq.freeze
|
|
168
182
|
end
|
|
183
|
+
|
|
184
|
+
# The names to leave out of what a version recorded. A root version is
|
|
185
|
+
# known to be the root's, so its own path's names apply; any other version
|
|
186
|
+
# does not say which path reached it, so only the names ignored everywhere
|
|
187
|
+
# do.
|
|
188
|
+
#: (root: bool) -> Array[String]
|
|
189
|
+
def recorded_attributes(root:)
|
|
190
|
+
root ? attributes_for('') : all
|
|
191
|
+
end
|
|
169
192
|
end
|
|
170
193
|
end
|