paper_trail_diff 0.13.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -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
  )
@@ -38,8 +38,9 @@ module PaperTrailDiff
38
38
  if @association_tree.empty?
39
39
  Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
40
40
  else
41
- # Prepared history orders versions that share a timestamp; reading
42
- # associations straight from PT-AT would resolve them by time alone.
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.
43
44
  comparison_batch([{ from: from_endpoint, to: to_endpoint }],
44
45
  preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
45
46
  end
@@ -52,12 +53,13 @@ module PaperTrailDiff
52
53
  count = comparisons.is_a?(Array) ? comparisons.length : 0
53
54
  payload = @instrumentation_payload.merge(comparison_count: count)
54
55
  Instrumentation.instrument('compare_many', payload) do
55
- comparison_batch(comparisons, preparer: method(:prepare_batch_model)).call
56
+ comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
56
57
  end
57
58
  end
58
59
 
59
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
60
- def timeline(record, from:, to:, within:, version_scope: nil, close_on: nil) # rubocop:disable Metrics/ParameterLists
60
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
61
+ def timeline(record, from:, to:, within:, version_scope: nil)
62
+ Endpoint.validate_root!(record)
61
63
  @traversal_preparer.call(record.class, historical: true)
62
64
  from, to = default_range(record, from, to, within)
63
65
  TimelineBuilder.new(
@@ -66,38 +68,40 @@ module PaperTrailDiff
66
68
  to: to,
67
69
  within: within,
68
70
  version_scope: version_scope,
69
- live_endpoint: live_endpoint_for(record, close_on, within),
71
+ live_endpoint: live_endpoint_for(record, within),
70
72
  snapshotter: @timeline_snapshotter
71
73
  ).build
72
74
  end
73
75
 
74
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
75
- def activity_timeline(record, from:, to:, within:, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
76
- payload = @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
76
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
77
+ def activity_timeline(record, from:, to:, within:, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
78
+ Endpoint.validate_root!(record)
79
+ payload = model_payload(record)
77
80
  Instrumentation.instrument('activity_timeline', payload) do
78
81
  @traversal_preparer.call(record.class, historical: true)
79
82
  from, to = default_range(record, from, to, within)
80
- live = live_endpoint_for(record, close_on, within)
83
+ live = live_endpoint_for(record, within)
81
84
  steps = activity_builder(
82
85
  record, from: from, to: to, within: within, version_scope: version_scope,
83
- live_endpoint: live, snapshots: snapshots, group: group
86
+ live_endpoint: live, view: activity_view(true, snapshots, group)
84
87
  ).build
85
88
  payload[:step_count] = steps.length
86
89
  steps
87
90
  end
88
91
  end
89
92
 
90
- #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
91
- def analyze(record, from:, to:, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
92
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
93
+ #: (untyped, from: untyped, to: untyped, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
94
+ def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
95
+ view = activity_view(activity, snapshots, group)
96
+ Endpoint.validate_root!(record)
93
97
  @traversal_preparer.call(record.class, historical: true)
94
98
  from, to = default_range(record, from, to, within)
95
- live = live_endpoint_for(record, close_on, within)
99
+ live = live_endpoint_for(record, within)
96
100
  if activity
97
- return analyze_activity(
101
+ return activity_builder(
98
102
  record, from: from, to: to, within: within, version_scope: version_scope,
99
- live_endpoint: live, snapshots: snapshots, group: group
100
- )
103
+ live_endpoint: live, view: view
104
+ ).analyze
101
105
  end
102
106
 
103
107
  TimelineBuilder.new(
@@ -107,85 +111,106 @@ module PaperTrailDiff
107
111
  end
108
112
 
109
113
  # Analyzes many roots over one shared range, preparing their history once.
110
- #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
111
- def analyze_many(records, within:, activity: false, version_scope: nil, close_on: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
112
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
113
- count = records.is_a?(Array) ? records.length : 0
114
- payload = @instrumentation_payload.merge(comparison_count: count)
115
- Instrumentation.instrument('analyze_many', payload) do
116
- AnalysisBatch.new(
117
- records,
118
- time_range: within.nil? ? nil : TimeRange.new(within), version_scope: version_scope,
119
- close_on_current: close_on_current?(close_on, within) || within.nil?,
120
- context_required: activity && !@association_tree.empty?,
121
- live_loader: method(:load_batch_endpoints),
122
- history_preparer: @historical_store.method(:prepare_batch),
123
- analyzer: batched_root_analyzer(activity, within: within, snapshots: snapshots,
124
- group: group)
125
- ).call
126
- end
114
+ #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
115
+ def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
116
+ analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
117
+ view: activity_view(activity, snapshots, group))
127
118
  end
128
119
 
129
120
  # Selects the roots from a relation before running the ordinary batch, so a
130
121
  # caller reporting on a population does not have to rediscover which of its
131
122
  # members changed. The roots the relation could not reach come back named
132
123
  # rather than dropped -- see `PaperTrailDiff.analyze_scope`.
133
- #: (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
134
- 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
135
- ActivityGrouping.validate!(group, activity: activity, snapshots: snapshots)
136
- @batch_safety.call(scope.all.model) if scope.respond_to?(:all) && scope.respond_to?(:where)
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
+ check_scope(scope)
137
128
  # @type var options: report_options
138
- options = { within: within, activity: activity, version_scope: version_scope,
139
- close_on: close_on, snapshots: snapshots, group: group }
129
+ options = { within: within, activity: activity, version_scope: version_scope, view: view }
140
130
  ScopedAnalysisBuilder.new(
141
131
  scope, limit: limit, within: within, historical_filter: historical_filter,
142
132
  max_filter_versions: max_filter_versions, include_deleted: include_deleted,
143
- analyzer: ->(records) { analyze_many(records, **options, within: within) },
133
+ analyzer: lambda { |records|
134
+ analyze_batch(records, within: within, activity: activity,
135
+ version_scope: version_scope, view: view)
136
+ },
144
137
  deleted_analyzer: lambda { |identities|
145
138
  analyze_deleted(scope.all.model, identities, options)
146
- }
139
+ },
140
+ # Checkpoints compare a root's own versions, so only activity can
141
+ # report a window in which just its associations changed.
142
+ activity_tree: (@association_tree if activity)
147
143
  ).call
148
144
  end
149
145
 
150
146
  private
151
147
 
148
+ #: (bool, bool, Symbol?) -> ActivityView
149
+ def activity_view(activity, snapshots, group)
150
+ ActivityView.build(activity: activity, snapshots: snapshots, group: group,
151
+ recorded: @recorded)
152
+ end
153
+
154
+ #: (untyped) -> Hash[Symbol, untyped]
155
+ def model_payload(record)
156
+ @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
157
+ end
158
+
159
+ #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
160
+ def analyze_batch(records, within:, activity:, version_scope:, view:)
161
+ count = records.is_a?(Array) ? records.length : 0
162
+ payload = @instrumentation_payload.merge(comparison_count: count)
163
+ Instrumentation.instrument('analyze_many', payload) do
164
+ AnalysisBatch.new(
165
+ records,
166
+ time_range: within.nil? ? nil : TimeRange.new(within), version_scope: version_scope,
167
+ context_required: activity && !@association_tree.empty?,
168
+ live_loader: method(:load_batch_endpoints),
169
+ history_preparer: @historical_store.method(:prepare_batch),
170
+ analyzer: batched_root_analyzer(activity, within: within, view: view)
171
+ ).call
172
+ end
173
+ end
174
+
175
+ # Analysis reads association history, so a request it would refuse is
176
+ # refused before the first selection query rather than once analysis starts.
177
+ #: (untyped) -> void
178
+ def check_scope(scope)
179
+ return unless scope.respond_to?(:all) && scope.respond_to?(:where)
180
+
181
+ @traversal_preparer.call(scope.all.model, historical: true)
182
+ end
183
+
152
184
  #: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
153
185
  def comparison_batch(comparisons, preparer:)
154
186
  ComparisonBatch.new(
155
187
  comparisons,
156
188
  live_loader: @live_endpoints, preparer: preparer,
157
189
  history_preparer: @historical_store.method(:prepare_batch),
190
+ version_history_preparer: @historical_store.method(:prepare_deleted_batch),
158
191
  historical_snapshotter: method(:historical_snapshot),
159
192
  live_normalizer: method(:normalize_live_snapshot)
160
193
  )
161
194
  end
162
195
 
196
+ # Refused before the current records load, rather than once analysis starts.
163
197
  #: (Array[untyped]) -> Hash[identity, untyped]
164
198
  def load_batch_endpoints(records)
165
- records.map(&:class).uniq.each { |model| @batch_safety.call(model) }
199
+ records.map(&:class).uniq.each { |model| @traversal_preparer.call(model, historical: true) }
166
200
  @live_endpoints.call(records)
167
201
  end
168
202
 
169
- #: (untyped, historical: bool) -> void
170
- def prepare_batch_model(model, historical:)
171
- @batch_safety.call(model, historical: historical)
172
- @traversal_preparer.call(model, historical: historical)
173
- end
174
-
175
- # @rbs @batch_safety: BatchSafety
176
-
177
203
  #: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
178
204
  def analyze_deleted(model, identities, options)
179
205
  within = options.fetch(:within)
180
- analyzer = batched_root_analyzer(
181
- options.fetch(:activity), within: within, snapshots: options.fetch(:snapshots),
182
- group: options.fetch(:group)
183
- )
206
+ analyzer = batched_root_analyzer(options.fetch(:activity), within: within,
207
+ view: options.fetch(:view))
184
208
  DeletedAnalysisBatch.new(
185
209
  model, identities: identities, time_range: within.nil? ? nil : TimeRange.new(within),
186
210
  version_scope: options.fetch(:version_scope),
187
211
  history_preparer: @historical_store.method(:prepare_deleted_batch),
188
- analyzer: analyzer
212
+ analyzer: analyzer,
213
+ context_required: options.fetch(:activity) && !@association_tree.empty?
189
214
  ).call
190
215
  end
191
216
 
@@ -193,6 +218,7 @@ module PaperTrailDiff
193
218
  # @rbs @live_endpoints: LiveEndpointProvider
194
219
  # @rbs @instrumentation_payload: Hash[Symbol, untyped]
195
220
  # @rbs @ignore_policy: IgnorePolicy
221
+ # @rbs @recorded: IgnorePolicy?
196
222
  # @rbs @traversal: AssociationTraversal
197
223
  # @rbs @traversal_preparer: TraversalPreparer
198
224
  # @rbs @snapshot_pool: SnapshotPool
@@ -201,24 +227,13 @@ module PaperTrailDiff
201
227
  # @rbs @timeline_snapshotter: TimelineSnapshotProvider
202
228
  # @rbs @activity_snapshotter: ActivitySnapshotProvider
203
229
 
204
- #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> Analysis
205
- def analyze_activity(record, from:, to:, within:, version_scope:, live_endpoint:, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
206
- activity_builder(
207
- record, from: from, to: to, within: within, version_scope: version_scope,
208
- live_endpoint: live_endpoint, snapshots: snapshots, group: group
209
- ).analyze
210
- end
211
-
212
- # Association membership is resolved by timestamp, so endpoints sharing one
213
- # cannot be told apart and any association change between them is invisible.
214
- # The result may still be correct -- nothing associated may have changed --
215
- # and the gem cannot tell which, since not seeing the change is the symptom.
216
- # So it reports the condition and leaves the judgement to the application.
230
+ # The result may still be correct -- nothing the path reaches may have
231
+ # changed -- and the gem cannot tell which, since not seeing the change is
232
+ # the symptom. So it reports the condition and leaves the judgement to the
233
+ # application.
217
234
  #: (untyped, untyped) -> void
218
235
  def notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
219
- return if @association_tree.empty?
220
- return unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
221
- return unless from_endpoint.created_at == to_endpoint.created_at
236
+ return unless ambiguous_association_boundary?(from_endpoint, to_endpoint)
222
237
 
223
238
  Instrumentation.notify(
224
239
  'ambiguous_association_boundary',
@@ -230,19 +245,19 @@ module PaperTrailDiff
230
245
  )
231
246
  end
232
247
 
233
- # A window with nothing recorded after its last change ends at the live
234
- # record, which holds the state that change produced -- whether the window
235
- # ended a moment ago or long before. `close_on: :current` asked for this
236
- # before it was the default and is still accepted. It names what ends a
237
- # wall-clock window, so it is meaningless for explicit endpoints.
238
- #: (Symbol?, untyped) -> bool
239
- def close_on_current?(close_on, within)
240
- unless close_on.nil? || close_on == CLOSE_ON_CURRENT
241
- raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
242
- end
243
- raise ConfigurationError, 'close_on: requires `within`' if close_on && within.nil?
244
-
245
- !within.nil?
248
+ # Loaded history orders two versions that share a timestamp by id, but
249
+ # PT-AT places association changes by timestamp alone, so only a path it
250
+ # reads can lose a change between them. A request the preparer refuses
251
+ # raises here, before anything is reported.
252
+ #: (untyped, untyped) -> bool
253
+ def ambiguous_association_boundary?(from_endpoint, to_endpoint)
254
+ return false if @association_tree.empty?
255
+ return false unless Endpoint.version?(from_endpoint) && Endpoint.version?(to_endpoint)
256
+ return false unless from_endpoint.created_at == to_endpoint.created_at
257
+
258
+ model_class = RecordedClass.for(from_endpoint)
259
+ @traversal_preparer.call(model_class, historical: true)
260
+ FallbackPaths.any?(@traversal, model_class, approximate: true)
246
261
  end
247
262
 
248
263
  # With neither a window nor endpoints, a range is the record's whole
@@ -255,12 +270,15 @@ module PaperTrailDiff
255
270
  [from.nil? ? :first : from, to.nil? ? record : to]
256
271
  end
257
272
 
273
+ # A window with nothing recorded after its last change ends at the live
274
+ # record, which holds the state that change produced -- whether the window
275
+ # ended a moment ago or long before. Explicit endpoints name their own end.
258
276
  # Only a saved row has current state to close on. A destroyed root's own
259
277
  # destroy version already terminates its history, and a reified or unsaved
260
278
  # instance stands for a state that is not in the table.
261
- #: (untyped, Symbol?, untyped) -> untyped
262
- def live_endpoint_for(record, close_on, within)
263
- return unless close_on_current?(close_on, within)
279
+ #: (untyped, untyped) -> untyped
280
+ def live_endpoint_for(record, within)
281
+ return if within.nil?
264
282
  return unless Endpoint.record?(record) && record.persisted?
265
283
 
266
284
  record
@@ -272,17 +290,20 @@ module PaperTrailDiff
272
290
  @timeline_snapshotter = TimelineSnapshotProvider.new(
273
291
  @historical_store, live_snapshotter: method(:live_snapshot)
274
292
  )
275
- @activity_snapshotter = build_activity_snapshotter
293
+ @activity_snapshotter = ActivitySnapshotProvider.new(
294
+ store: @historical_store, snapshotter: method(:snapshot_at),
295
+ refresher: method(:branch_refresher)
296
+ )
276
297
  end
277
298
 
278
- #: (bool, within: untyped, snapshots: bool, group: Symbol?) -> BatchedRootAnalyzer
279
- def batched_root_analyzer(activity, within:, snapshots:, group:)
299
+ #: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
300
+ def batched_root_analyzer(activity, within:, view:)
280
301
  BatchedRootAnalyzer.new(
281
302
  tree: @association_tree,
282
303
  timeline_snapshotter: @timeline_snapshotter,
283
304
  activity_snapshotter: @activity_snapshotter,
284
305
  preparer: @traversal_preparer.method(:call),
285
- activity: activity, within: within, snapshots: snapshots, group: group
306
+ activity: activity, within: within, view: view
286
307
  )
287
308
  end
288
309
 
@@ -296,27 +317,23 @@ module PaperTrailDiff
296
317
  )
297
318
  end
298
319
 
299
- #: () -> ActivitySnapshotProvider
300
- def build_activity_snapshotter
301
- refresher = BranchSnapshotRefresher.new(
320
+ # Refreshes one root's snapshots, reading with the history prepared for it.
321
+ #: (PreparedActivitySnapshots) -> BranchSnapshotRefresher
322
+ def branch_refresher(snapshots)
323
+ BranchSnapshotRefresher.new(
302
324
  tree: @association_tree, ignore_policy: @ignore_policy,
303
325
  traversal: @traversal, pool: @snapshot_pool,
304
326
  normalizer: @normalizer,
305
- full_snapshotter: method(:snapshot_at),
306
- partial_snapshotter: @historical_store.method(:custom),
307
- association_reader: @historical_store.method(:association_reader),
308
- record_transition: @historical_store.method(:record_transition),
309
- prepared_record_after: @historical_store.method(:record_after)
310
- )
311
- ActivitySnapshotProvider.new(
312
- snapshotter: method(:snapshot_at), refresher: refresher,
313
- preparer: @historical_store.method(:prepare),
314
- activity_index: @historical_store.method(:activity_index)
327
+ full_snapshotter: snapshots.method(:call),
328
+ partial_snapshotter: snapshots.method(:custom),
329
+ association_reader: snapshots.method(:association_reader),
330
+ record_transition: snapshots.method(:record_transition),
331
+ prepared_record_after: snapshots.method(:record_after)
315
332
  )
316
333
  end
317
334
 
318
- #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?live_endpoint: untyped, ?snapshots: bool, ?group: Symbol?) -> ActivityTimelineBuilder
319
- def activity_builder(record, from:, to:, within:, version_scope: nil, live_endpoint: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
335
+ #: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped, view: ActivityView) -> ActivityTimelineBuilder
336
+ def activity_builder(record, from:, to:, within:, version_scope:, live_endpoint:, view:) # rubocop:disable Metrics/ParameterLists
320
337
  ActivityTimelineBuilder.new(
321
338
  record,
322
339
  range: TimelineRange.new(
@@ -325,8 +342,7 @@ module PaperTrailDiff
325
342
  ),
326
343
  tree: @association_tree,
327
344
  snapshotter: @activity_snapshotter,
328
- snapshots: snapshots,
329
- group: group
345
+ view: view
330
346
  )
331
347
  end
332
348
 
@@ -340,16 +356,11 @@ module PaperTrailDiff
340
356
  snapshot_at(version, version)
341
357
  end
342
358
 
343
- #: (untyped) -> RecordSnapshot?
344
- def uncached_historical_snapshot(version)
345
- @historical_store.uncached(version, version)
346
- end
347
-
348
- #: (untyped, untyped) -> RecordSnapshot?
349
- def snapshot_at(root_endpoint, context_endpoint)
359
+ #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
360
+ def snapshot_at(root_endpoint, context_endpoint, history: nil)
350
361
  return live_snapshot(root_endpoint) if Endpoint.record?(context_endpoint)
351
362
 
352
- @historical_store.call(root_endpoint, context_endpoint)
363
+ @historical_store.call(root_endpoint, context_endpoint, history: history)
353
364
  end
354
365
 
355
366
  #: (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:)
@@ -30,12 +31,13 @@ module PaperTrailDiff
30
31
 
31
32
  #: (untyped, AssociationTree, String, untyped) -> void
32
33
  def validate_association(record, tree, path, reflection)
33
- association_path = Support.association_path(path, reflection.name.to_s)
34
+ association_path = Support.association_path(path, reflection.name)
34
35
  association = record.association(reflection.name)
35
36
  unless association.loaded?
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