paper_trail_diff 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -7,16 +7,16 @@ module PaperTrailDiff
7
7
  # the only place allowed to know about both PaperTrail and the pure engine.
8
8
  # Reconstruction logic lives in the collaborators it wires together.
9
9
  class PaperTrailAdapter # rubocop:disable Metrics/ClassLength
10
- # The only thing a wall-clock window can close on besides a later version.
11
- CLOSE_ON_CURRENT = :current
12
-
13
- #: (associations: Array[String | Symbol], ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> void
14
- def initialize(associations:, ignore:, reload_live_endpoints: true, allow_expensive: false)
10
+ # `recorded_changes:` reads what each activity boundary's version recorded.
11
+ # `allow_approximate:` accepts association paths read with PT-AT.
12
+ #: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
13
+ def initialize(associations:, ignore:, reload_live_endpoints: true, recorded_changes: false, allow_approximate: false) # rubocop:disable Metrics/MethodLength, Layout/LineLength
15
14
  @association_tree = AssociationTree.build(associations)
16
15
  @ignore_policy = IgnorePolicy.build(ignore, association_paths: @association_tree.paths)
16
+ @recorded = (@ignore_policy if recorded_changes)
17
17
  @traversal = AssociationTraversal.new(@association_tree)
18
- @batch_safety = BatchSafety.new(@traversal, allow_expensive: allow_expensive)
19
- @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal)
18
+ @traversal_preparer = TraversalPreparer.new(tree: @association_tree, traversal: @traversal,
19
+ allow_approximate: allow_approximate)
20
20
  @live_endpoints = LiveEndpointProvider.new(
21
21
  tree: @association_tree, traversal: @traversal, reload: reload_live_endpoints
22
22
  )
@@ -35,14 +35,16 @@ module PaperTrailDiff
35
35
  Instrumentation.instrument('compare', payload) do
36
36
  Endpoint.validate_pair!(from_endpoint, to_endpoint)
37
37
  notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
38
- if @association_tree.empty?
39
- Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
40
- else
41
- # Prepared history orders versions that share a timestamp and finds
42
- # children that later moved away; reading associations straight from
43
- # PT-AT would resolve them by time alone and miss those children.
44
- comparison_batch([{ from: from_endpoint, to: to_endpoint }],
45
- preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
38
+ ReadSnapshot.call([from_endpoint, to_endpoint]) do
39
+ if @association_tree.empty?
40
+ Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
41
+ else
42
+ # Prepared history orders versions that share a timestamp and finds
43
+ # children that later moved away; reading associations straight from
44
+ # PT-AT would resolve them by time alone and miss those children.
45
+ comparison_batch([{ from: from_endpoint, to: to_endpoint }],
46
+ preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
47
+ end
46
48
  end
47
49
  end
48
50
  end
@@ -53,114 +55,147 @@ module PaperTrailDiff
53
55
  count = comparisons.is_a?(Array) ? comparisons.length : 0
54
56
  payload = @instrumentation_payload.merge(comparison_count: count)
55
57
  Instrumentation.instrument('compare_many', payload) do
56
- comparison_batch(comparisons, preparer: method(:prepare_batch_model)).call
58
+ ReadSnapshot.call(comparison_endpoints(comparisons)) do
59
+ comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
60
+ end
57
61
  end
58
62
  end
59
63
 
60
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
61
- def timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
62
- @traversal_preparer.call(record.class, historical: true)
63
- from, to = default_range(record, from, to, within)
64
- TimelineBuilder.new(
65
- record,
66
- from: from,
67
- to: to,
68
- within: within,
69
- version_scope: version_scope,
70
- live_endpoint: live_endpoint_for(record, close_on, within),
71
- snapshotter: @timeline_snapshotter
72
- ).build
73
- end
74
-
75
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
76
- def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
77
- payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
78
- Instrumentation.instrument('activity_timeline', payload) do
64
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
65
+ def timeline(record, from:, to:, within:, version_scope: nil)
66
+ Endpoint.validate_root!(record)
67
+ ReadSnapshot.call([record]) do
79
68
  @traversal_preparer.call(record.class, historical: true)
80
69
  from, to = default_range(record, from, to, within)
81
- live = live_endpoint_for(record, close_on, within)
82
- steps = activity_builder(
83
- record, from: from, to: to, within: within, version_scope: version_scope,
84
- live_endpoint: live, snapshots: snapshots, group: group
70
+ TimelineBuilder.new(
71
+ record,
72
+ from: from,
73
+ to: to,
74
+ within: within,
75
+ version_scope: version_scope,
76
+ live_endpoint: live_endpoint_for(record, within),
77
+ snapshotter: @timeline_snapshotter
85
78
  ).build
79
+ end
80
+ end
81
+
82
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
83
+ def activity_timeline(record, from:, to:, within:, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
84
+ Endpoint.validate_root!(record)
85
+ payload = model_payload(record)
86
+ Instrumentation.instrument('activity_timeline', payload) do
87
+ steps = ReadSnapshot.call([record]) do
88
+ @traversal_preparer.call(record.class, historical: true)
89
+ from, to = default_range(record, from, to, within)
90
+ live = live_endpoint_for(record, within)
91
+ activity_builder(
92
+ record, from: from, to: to, within: within, version_scope: version_scope,
93
+ live_endpoint: live, view: activity_view(true, snapshots, group)
94
+ ).build
95
+ end
86
96
  payload[:step_count] = steps.length
87
97
  steps
88
98
  end
89
99
  end
90
100
 
91
- #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
92
- def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
93
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
94
- @traversal_preparer.call(record.class, historical: true)
95
- from, to = default_range(record, from, to, within)
96
- live = live_endpoint_for(record, close_on, within)
97
- if activity
98
- return analyze_activity(
99
- record, from: from, to: to, within: within, version_scope: version_scope,
100
- live_endpoint: live, snapshots: snapshots, group: group
101
- )
101
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
102
+ def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
103
+ view = activity_view(activity, snapshots, group)
104
+ Endpoint.validate_root!(record)
105
+ ReadSnapshot.call([record]) do
106
+ analyze_record(record, from: from, to: to, within: within, activity: activity,
107
+ version_scope: version_scope, view: view)
102
108
  end
103
-
104
- TimelineBuilder.new(
105
- record, from: from, to: to, within: within, version_scope: version_scope,
106
- live_endpoint: live, snapshotter: @timeline_snapshotter
107
- ).analyze
108
109
  end
109
110
 
110
111
  # Analyzes many roots over one shared range, preparing their history once.
111
- #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
112
- def analyze_many(records, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
113
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
112
+ #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
113
+ def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
114
+ ReadSnapshot.call(records.is_a?(Array) ? records : []) do
115
+ analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
116
+ view: activity_view(activity, snapshots, group))
117
+ end
118
+ end
119
+
120
+ # Selects the roots from a relation before running the ordinary batch, so a
121
+ # caller reporting on a population does not have to rediscover which of its
122
+ # members changed. The roots the relation could not reach come back named
123
+ # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
124
+ #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
125
+ def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
126
+ view = activity_view(activity, snapshots, group)
127
+ ReadSnapshot.call([scope]) do
128
+ check_scope(scope)
129
+ scoped_builder(scope, limit: limit, within: within, activity: activity,
130
+ version_scope: version_scope, historical_filter: historical_filter,
131
+ max_filter_versions: max_filter_versions,
132
+ include_deleted: include_deleted, view: view).call
133
+ end
134
+ end
135
+
136
+ private
137
+
138
+ #: (bool, bool, Symbol?) -> ActivityView
139
+ def activity_view(activity, snapshots, group)
140
+ ActivityView.build(activity: activity, snapshots: snapshots, group: group,
141
+ recorded: @recorded)
142
+ end
143
+
144
+ #: (untyped) -> Hash[Symbol, untyped]
145
+ def model_payload(record)
146
+ @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
147
+ end
148
+
149
+ #: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
150
+ def analyze_record(record, from:, to:, within:, activity:, version_scope:, view:) # rubocop:disable Metrics/ParameterLists
151
+ @traversal_preparer.call(record.class, historical: true)
152
+ from, to = default_range(record, from, to, within)
153
+ live = live_endpoint_for(record, within)
154
+ builder = if activity
155
+ activity_builder(
156
+ record, from: from, to: to, within: within, version_scope: version_scope,
157
+ live_endpoint: live, view: view
158
+ )
159
+ else
160
+ TimelineBuilder.new(
161
+ record, from: from, to: to, within: within, version_scope: version_scope,
162
+ live_endpoint: live, snapshotter: @timeline_snapshotter
163
+ )
164
+ end
165
+ builder.analyze.with_window(builder.window)
166
+ end
167
+
168
+ #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
169
+ def analyze_batch(records, within:, activity:, version_scope:, view:)
114
170
  count = records.is_a?(Array) ? records.length : 0
115
171
  payload = @instrumentation_payload.merge(comparison_count: count)
116
172
  Instrumentation.instrument('analyze_many', payload) do
117
173
  AnalysisBatch.new(
118
174
  records,
119
175
  time_range: within.nil? ? nil : TimeRange.new(within), version_scope: version_scope,
120
- close_on_current: close_on_current?(close_on, within) || within.nil?,
121
176
  context_required: activity && !@association_tree.empty?,
122
177
  live_loader: method(:load_batch_endpoints),
123
178
  history_preparer: @historical_store.method(:prepare_batch),
124
- analyzer: batched_root_analyzer(activity, within: within, snapshots: snapshots,
125
- group: group)
179
+ analyzer: batched_root_analyzer(activity, within: within, view: view)
126
180
  ).call
127
181
  end
128
182
  end
129
183
 
130
- # Selects the roots from a relation before running the ordinary batch, so a
131
- # caller reporting on a population does not have to rediscover which of its
132
- # members changed. The roots the relation could not reach come back named
133
- # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
134
- #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
135
- def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
136
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
137
- check_scope(scope, activity)
138
- # @type var options: report_options
139
- options = { within: within, activity: activity, version_scope: version_scope,
140
- close_on: close_on, snapshots: snapshots, group: group }
141
- ScopedAnalysisBuilder.new(
142
- scope, limit: limit, within: within, historical_filter: historical_filter,
143
- max_filter_versions: max_filter_versions, include_deleted: include_deleted,
144
- analyzer: ->(records) { analyze_many(records, **options, within: within) },
145
- deleted_analyzer: lambda { |identities|
146
- analyze_deleted(scope.all.model, identities, options)
147
- },
148
- # Checkpoints compare a root's own versions, so only activity can
149
- # report a window in which just its associations changed.
150
- activity_tree: (@association_tree if activity)
151
- ).call
152
- end
184
+ # Analysis reads association history, so a request it would refuse is
185
+ # refused before the first selection query rather than once analysis starts.
186
+ #: (untyped) -> void
187
+ def check_scope(scope)
188
+ return unless scope.respond_to?(:all) && scope.respond_to?(:where)
153
189
 
154
- private
190
+ @traversal_preparer.call(scope.all.model, historical: true)
191
+ end
155
192
 
156
- # Selecting by activity reads association history, so it must be available
157
- # before the first selection query rather than once analysis starts.
158
- #: (untyped, bool) -> void
159
- def check_scope(scope, activity)
160
- return unless scope.respond_to?(:all) && scope.respond_to?(:where)
193
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
194
+ #: (untyped) -> Array[untyped]
195
+ def comparison_endpoints(comparisons)
196
+ return [] unless comparisons.is_a?(Array)
161
197
 
162
- @batch_safety.call(scope.all.model)
163
- @traversal_preparer.call(scope.all.model, historical: true) if activity
198
+ comparisons.grep(Hash).flat_map(&:values)
164
199
  end
165
200
 
166
201
  #: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
@@ -175,27 +210,18 @@ module PaperTrailDiff
175
210
  )
176
211
  end
177
212
 
213
+ # Refused before the current records load, rather than once analysis starts.
178
214
  #: (Array[untyped]) -> Hash[identity, untyped]
179
215
  def load_batch_endpoints(records)
180
- records.map(&:class).uniq.each { |model| @batch_safety.call(model) }
216
+ records.map(&:class).uniq.each { |model| @traversal_preparer.call(model, historical: true) }
181
217
  @live_endpoints.call(records)
182
218
  end
183
219
 
184
- #: (untyped, historical: bool) -> void
185
- def prepare_batch_model(model, historical:)
186
- @batch_safety.call(model)
187
- @traversal_preparer.call(model, historical: historical)
188
- end
189
-
190
- # @rbs @batch_safety: BatchSafety
191
-
192
220
  #: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
193
221
  def analyze_deleted(model, identities, options)
194
222
  within = options.fetch(:within)
195
- analyzer = batched_root_analyzer(
196
- options.fetch(:activity), within: within, snapshots: options.fetch(:snapshots),
197
- group: options.fetch(:group)
198
- )
223
+ analyzer = batched_root_analyzer(options.fetch(:activity), within: within,
224
+ view: options.fetch(:view))
199
225
  DeletedAnalysisBatch.new(
200
226
  model, identities: identities, time_range: within.nil? ? nil : TimeRange.new(within),
201
227
  version_scope: options.fetch(:version_scope),
@@ -205,10 +231,31 @@ module PaperTrailDiff
205
231
  ).call
206
232
  end
207
233
 
234
+ #: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
235
+ def scoped_builder(scope, limit:, within:, activity:, version_scope:, historical_filter:, max_filter_versions:, include_deleted:, view:) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
236
+ # @type var options: report_options
237
+ options = { within: within, activity: activity, version_scope: version_scope, view: view }
238
+ ScopedAnalysisBuilder.new(
239
+ scope, limit: limit, within: within, historical_filter: historical_filter,
240
+ max_filter_versions: max_filter_versions, include_deleted: include_deleted,
241
+ analyzer: lambda { |records|
242
+ analyze_batch(records, within: within, activity: activity,
243
+ version_scope: version_scope, view: view)
244
+ },
245
+ deleted_analyzer: lambda { |identities|
246
+ analyze_deleted(scope.all.model, identities, options)
247
+ },
248
+ # Checkpoints compare a root's own versions, so only activity can
249
+ # report a window in which just its associations changed.
250
+ activity_tree: (@association_tree if activity), version_scope: version_scope
251
+ )
252
+ end
253
+
208
254
  # @rbs @association_tree: AssociationTree
209
255
  # @rbs @live_endpoints: LiveEndpointProvider
210
256
  # @rbs @instrumentation_payload: Hash[Symbol, untyped]
211
257
  # @rbs @ignore_policy: IgnorePolicy
258
+ # @rbs @recorded: IgnorePolicy?
212
259
  # @rbs @traversal: AssociationTraversal
213
260
  # @rbs @traversal_preparer: TraversalPreparer
214
261
  # @rbs @snapshot_pool: SnapshotPool
@@ -217,24 +264,13 @@ module PaperTrailDiff
217
264
  # @rbs @timeline_snapshotter: TimelineSnapshotProvider
218
265
  # @rbs @activity_snapshotter: ActivitySnapshotProvider
219
266
 
220
- #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
221
- def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
222
- activity_builder(
223
- record, from: from, to: to, within: within, version_scope: version_scope,
224
- live_endpoint: live_endpoint, snapshots: snapshots, group: group
225
- ).analyze
226
- end
227
-
228
- # Association membership is resolved by timestamp, so endpoints sharing one
229
- # cannot be told apart and any association change between them is invisible.
230
- # The result may still be correct -- nothing associated may have changed --
231
- # and the gem cannot tell which, since not seeing the change is the symptom.
232
- # So it reports the condition and leaves the judgement to the application.
267
+ # The result may still be correct -- nothing the path reaches may have
268
+ # changed -- and the gem cannot tell which, since not seeing the change is
269
+ # the symptom. So it reports the condition and leaves the judgement to the
270
+ # application.
233
271
  #: (untyped, untyped) -> void
234
272
  def notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
235
- return if @association_tree.empty?
236
- return unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
237
- return unless from_endpoint.created_at == to_endpoint.created_at
273
+ return unless ambiguous_association_boundary?(from_endpoint, to_endpoint)
238
274
 
239
275
  Instrumentation.notify(
240
276
  'ambiguous_association_boundary',
@@ -246,19 +282,19 @@ module PaperTrailDiff
246
282
  )
247
283
  end
248
284
 
249
- # A window with nothing recorded after its last change ends at the live
250
- # record, which holds the state that change produced -- whether the window
251
- # ended a moment ago or long before. `close_on: :current` asked for this
252
- # before it was the default and is still accepted. It names what ends a
253
- # wall-clock window, so it is meaningless for explicit endpoints.
254
- #: (Symbol?, untyped) -> bool
255
- def close_on_current?(close_on, within)
256
- unless close_on.nil? || close_on == CLOSE_ON_CURRENT
257
- raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
258
- end
259
- raise ConfigurationError, 'close_on: requires `within`' if close_on && within.nil?
260
-
261
- !within.nil?
285
+ # Loaded history orders two versions that share a timestamp by id, but
286
+ # PT-AT places association changes by timestamp alone, so only a path it
287
+ # reads can lose a change between them. A request the preparer refuses
288
+ # raises here, before anything is reported.
289
+ #: (untyped, untyped) -> bool
290
+ def ambiguous_association_boundary?(from_endpoint, to_endpoint)
291
+ return false if @association_tree.empty?
292
+ return false unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
293
+ return false unless from_endpoint.created_at == to_endpoint.created_at
294
+
295
+ model_class = RecordedClass.for(from_endpoint)
296
+ @traversal_preparer.call(model_class, historical: true)
297
+ FallbackPaths.any?(@traversal, model_class, approximate: true)
262
298
  end
263
299
 
264
300
  # With neither a window nor endpoints, a range is the record's whole
@@ -271,12 +307,15 @@ module PaperTrailDiff
271
307
  [from.nil? ? :first : from, to.nil? ? record : to]
272
308
  end
273
309
 
310
+ # A window with nothing recorded after its last change ends at the live
311
+ # record, which holds the state that change produced -- whether the window
312
+ # ended a moment ago or long before. Explicit endpoints name their own end.
274
313
  # Only a saved row has current state to close on. A destroyed root's own
275
314
  # destroy version already terminates its history, and a reified or unsaved
276
315
  # instance stands for a state that is not in the table.
277
- #: (untyped, Symbol?, untyped) -> untyped
278
- def live_endpoint_for(record, close_on, within)
279
- return unless close_on_current?(close_on, within)
316
+ #: (untyped, untyped) -> untyped
317
+ def live_endpoint_for(record, within)
318
+ return if within.nil?
280
319
  return unless Endpoint.record?(record) && record.persisted?
281
320
 
282
321
  record
@@ -288,17 +327,20 @@ module PaperTrailDiff
288
327
  @timeline_snapshotter = TimelineSnapshotProvider.new(
289
328
  @historical_store, live_snapshotter: method(:live_snapshot)
290
329
  )
291
- @activity_snapshotter = build_activity_snapshotter
330
+ @activity_snapshotter = ActivitySnapshotProvider.new(
331
+ store: @historical_store, snapshotter: method(:snapshot_at),
332
+ refresher: method(:branch_refresher)
333
+ )
292
334
  end
293
335
 
294
- #: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
295
- def batched_root_analyzer(activity, within:, snapshots:, group:)
336
+ #: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
337
+ def batched_root_analyzer(activity, within:, view:)
296
338
  BatchedRootAnalyzer.new(
297
339
  tree: @association_tree,
298
340
  timeline_snapshotter: @timeline_snapshotter,
299
341
  activity_snapshotter: @activity_snapshotter,
300
342
  preparer: @traversal_preparer.method(:call),
301
- activity: activity, within: within, snapshots: snapshots, group: group
343
+ activity: activity, within: within, view: view
302
344
  )
303
345
  end
304
346
 
@@ -312,27 +354,23 @@ module PaperTrailDiff
312
354
  )
313
355
  end
314
356
 
315
- #: () -> ActivitySnapshotProvider
316
- def build_activity_snapshotter
317
- refresher = BranchSnapshotRefresher.new(
357
+ # Refreshes one root's snapshots, reading with the history prepared for it.
358
+ #: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
359
+ def branch_refresher(snapshots)
360
+ BranchSnapshotRefresher.new(
318
361
  tree: @association_tree, ignore_policy: @ignore_policy,
319
362
  traversal: @traversal, pool: @snapshot_pool,
320
363
  normalizer: @normalizer,
321
- full_snapshotter: method(:snapshot_at),
322
- partial_snapshotter: @historical_store.method(:custom),
323
- association_reader: @historical_store.method(:association_reader),
324
- record_transition: @historical_store.method(:record_transition),
325
- prepared_record_after: @historical_store.method(:record_after)
326
- )
327
- ActivitySnapshotProvider.new(
328
- snapshotter: method(:snapshot_at), refresher: refresher,
329
- preparer: @historical_store.method(:prepare),
330
- activity_index: @historical_store.method(:activity_index)
364
+ full_snapshotter: snapshots.method(:call),
365
+ partial_snapshotter: snapshots.method(:custom),
366
+ association_reader: snapshots.method(:association_reader),
367
+ record_transition: snapshots.method(:record_transition),
368
+ prepared_record_after: snapshots.method(:record_after)
331
369
  )
332
370
  end
333
371
 
334
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
335
- def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
372
+ #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
373
+ def activity_builder(record, from:, to:, within:, version_scope:, live_endpoint:, view:) # rubocop:disable Metrics/ParameterLists
336
374
  ActivityTimelineBuilder.new(
337
375
  record,
338
376
  range: TimelineRange.new(
@@ -341,8 +379,7 @@ module PaperTrailDiff
341
379
  ),
342
380
  tree: @association_tree,
343
381
  snapshotter: @activity_snapshotter,
344
- snapshots: snapshots,
345
- group: group
382
+ view: view
346
383
  )
347
384
  end
348
385
 
@@ -356,16 +393,11 @@ module PaperTrailDiff
356
393
  snapshot_at(version, version)
357
394
  end
358
395
 
359
- #: (untyped) -> RecordSnapshot?
360
- def uncached_historical_snapshot(version)
361
- @historical_store.uncached(version, version)
362
- end
363
-
364
- #: (untyped, untyped) -> RecordSnapshot?
365
- def snapshot_at(root_endpoint, context_endpoint)
396
+ #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
397
+ def snapshot_at(root_endpoint, context_endpoint, history: nil)
366
398
  return live_snapshot(root_endpoint) if Endpoint.record?(context_endpoint)
367
399
 
368
- @historical_store.call(root_endpoint, context_endpoint)
400
+ @historical_store.call(root_endpoint, context_endpoint, history: history)
369
401
  end
370
402
 
371
403
  #: (untyped) -> RecordSnapshot
@@ -2,7 +2,8 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Validates and reuses caller-owned live records without issuing association queries.
5
+ # Validates and reuses caller-owned live records, reading again only the
6
+ # associations a preload of many records cannot have loaded correctly.
6
7
  class PreloadedEndpointBatchLoader
7
8
  #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
8
9
  def initialize(tree:, traversal:)
@@ -36,6 +37,7 @@ module PaperTrailDiff
36
37
  message = "current endpoint association is not preloaded: #{association_path}"
37
38
  raise UnloadedAssociationError, message
38
39
  end
40
+ read_alone(association) unless BatchPreload.safe?(reflection)
39
41
 
40
42
  subtree = tree.child(reflection.name)
41
43
  return unless subtree
@@ -44,5 +46,15 @@ module PaperTrailDiff
44
46
  validate_record(child, subtree, path: association_path)
45
47
  end
46
48
  end
49
+
50
+ # Preloading many records applies a limit or offset to all of them
51
+ # together, so what a caller preloaded cannot be trusted: one record keeps
52
+ # another's share, or none. Such an association is read again for each
53
+ # record, as reloading reads it.
54
+ #: (untyped) -> void
55
+ def read_alone(association)
56
+ association.reset
57
+ association.load_target
58
+ end
47
59
  end
48
60
  end
@@ -3,11 +3,18 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Shares association event discovery across every root in a prepared graph.
6
+ #
7
+ # The candidates are the records the prepared snapshots can hold: those
8
+ # recorded under an owner from the start onward, and those under it now. A
9
+ # key changed without a version is recorded only by the record's next
10
+ # version, or by the current row, either of which can come after the range,
11
+ # and the snapshots read it from there. ActivityTreeFilter leaves out the
12
+ # events of a candidate that was outside the tree throughout.
6
13
  class PreparedActivityIndex
7
- #: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
8
- def initialize(records, root_versions, start_at:, end_at:)
14
+ #: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
15
+ def initialize(records, root_versions, start_at:)
9
16
  @records = records
10
- @range = ActivityRange.new(start_at, end_at)
17
+ @range = ActivityRange.new(start_at, nil)
11
18
  @roots = root_versions.group_by { |version| [version.item_type, version.item_id.to_s] }
12
19
  @nodes = {} #: Hash[String, Array[untyped]]
13
20
  # Rows are cached by reflection, which a subclass shares with its base.
@@ -73,17 +80,15 @@ module PaperTrailDiff
73
80
  historical, live = @children[reflection] ||= child_rows(model, reflection)
74
81
  empty = [] #: Array[untyped]
75
82
  selected = historical_ids(reflection.klass, ids, historical, range)
76
- selected |= ids.flat_map { |id| live.fetch(id.to_s, empty) } if range.current_end?
77
- selected.uniq
83
+ selected | ids.flat_map { |id| live.fetch(id.to_s, empty) }
78
84
  end
79
85
 
80
- # The `belongs_to` targets each owner pointed at in the range: at its start
81
- # and after each change inside it, plus the live row at a current end.
86
+ # The `belongs_to` targets each owner pointed at from the range's start
87
+ # onward, plus the live row.
82
88
  #: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
83
89
  def target_rows(model, ids, reflection, range)
84
90
  historical, live = @targets[reflection] ||= target_candidates(model, reflection)
85
- rows = eligible_rows(model, rows_for(historical, ids), range)
86
- range.current_end? ? rows + rows_for(live, ids) : rows
91
+ eligible_rows(model, rows_for(historical, ids), range) + rows_for(live, ids)
87
92
  end
88
93
 
89
94
  #: (untyped, untyped) -> bool
@@ -153,8 +158,7 @@ module PaperTrailDiff
153
158
  #: (untyped, Array[ActivityTargetCandidateLoader::Row], ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
154
159
  def eligible_rows(model, rows, range)
155
160
  rows.select do |row|
156
- eligible_version?(model, row.owner_id, row.created_at, row.event, range) &&
157
- range.recorded_before_end?(row.created_at, row.version_id)
161
+ eligible_version?(model, row.owner_id, row.created_at, row.event, range)
158
162
  end
159
163
  end
160
164
 
@@ -170,7 +174,7 @@ module PaperTrailDiff
170
174
  # survive a later pre-window reassignment just because that owner is absent.
171
175
  #: (untyped, untyped, untyped, String?, ActivityRange) -> bool
172
176
  def eligible_version?(model, id, timestamp, event, range)
173
- return timestamp <= range.end_time if timestamp >= range.start_time
177
+ return true if timestamp >= range.start_time
174
178
  return false if event == 'destroy'
175
179
 
176
180
  later = @records.versions_for_id(model, id)
@@ -189,7 +193,7 @@ module PaperTrailDiff
189
193
  # A version without a transaction id names no rows, so it can stay in.
190
194
  #: (Array[untyped]) -> Array[untyped]
191
195
  def transaction_ids(versions)
192
- versions.map { |version| version.transaction_id if version.respond_to?(:transaction_id) }.uniq
196
+ versions.map { |version| VersionBoundary.transaction_id(version) }.uniq
193
197
  end
194
198
  end
195
199
  end
@@ -111,7 +111,8 @@ module PaperTrailDiff
111
111
  #: (untyped, Array[untyped], untyped, String) -> untyped
112
112
  def historical_child_relation(owner_class, owner_ids, reflection, foreign_key)
113
113
  version_class = owner_class.paper_trail.version_class
114
- owner_class.paper_trail.version_association_class.joins(:version).where(
114
+ associations = owner_class.paper_trail.version_association_class
115
+ VersionTable.joined(associations, version_class).where(
115
116
  foreign_key_name: foreign_key,
116
117
  foreign_key_id: owner_ids,
117
118
  foreign_type: parent_types(owner_class)