paper_trail_diff 0.17.1 → 0.18.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 (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -11,34 +11,52 @@ module PaperTrailDiff
11
11
  # and the snapshots read it from there. ActivityTreeFilter leaves out the
12
12
  # events of a candidate that was outside the tree throughout.
13
13
  class PreparedActivityIndex
14
+ # A belongs_to target an owner's recorded state names. A plain class
15
+ # rather than Data.define, which arrived in Ruby 3.2 while this gem
16
+ # supports 3.1.
17
+ class TargetRow
18
+ attr_reader :owner_id #: untyped
19
+ attr_reader :foreign_key_id #: untyped
20
+ attr_reader :foreign_type #: String?
21
+
22
+ #: (untyped, untyped, String?) -> void
23
+ def initialize(owner_id, foreign_key_id, foreign_type)
24
+ @owner_id = owner_id
25
+ @foreign_key_id = foreign_key_id
26
+ @foreign_type = foreign_type
27
+ freeze
28
+ end
29
+ end
30
+
14
31
  # The children the history's owners had, which its edge loader reads
15
32
  # first for most of them.
16
33
  attr_reader :children #: PreparedChildCandidates
17
34
 
18
- #: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
19
- def initialize(records, root_versions, start_at:)
35
+ #: (PreparedRecordIndex, start_at: untyped) -> void
36
+ def initialize(records, start_at:)
20
37
  @records = records
21
- @start_at = start_at
22
- @children = PreparedChildCandidates.new(start_at)
23
- @roots = root_versions.group_by { |version| Endpoint.identity(version) }
38
+ @children = PreparedChildCandidates.new(start_at, records.end_time)
24
39
  @nodes = {} #: Hash[String, Array[untyped]]
25
- # Rows are cached by reflection, which a subclass shares with its base.
26
- @targets = {} #: Hash[untyped, untyped]
27
- @rows = {} #: Hash[untyped, Hash[String, Array[untyped]]]
28
40
  @conditions = ScopeCondition::Cache.new
41
+ @judge = JoinRunJudge.new(records, @conditions)
29
42
  end
30
43
 
44
+ # See PreparedRecordIndex#transaction_ends.
45
+ #: (Array[untyped]) -> TransactionEnds
46
+ def transaction_ends(versions) = @records.transaction_ends(versions)
47
+
31
48
  #: (untyped, Array[untyped]) -> void
32
49
  def register(model, ids)
33
50
  name = model.base_class.name
34
51
  @nodes[name] = (@nodes.fetch(name, []) | ids)
35
52
  end
36
53
 
54
+ # A record's events are the versions the history loaded for it, a root of
55
+ # the batch's too: met in another root's tree, its versions after the
56
+ # window are events of that tree as well.
37
57
  #: (untyped, Array[untyped]) -> Array[untyped]
38
58
  def versions(model, ids)
39
- ids.flat_map do |id|
40
- @roots[Support.record_identity(model, id)] || @records.versions_for_id(model, id)
41
- end
59
+ ids.flat_map { |id| @records.versions_for_id(model, id) }
42
60
  end
43
61
 
44
62
  # Children are found by key across the whole table, so an association to
@@ -71,14 +89,19 @@ module PaperTrailDiff
71
89
  # change nothing these `owners` show. As events they would open steps of
72
90
  # their own, and inside a transaction, where a change surfaces one event
73
91
  # late, take the credit for another record's change.
92
+ #
93
+ # A row of a through that goes through another, such as a member under
94
+ # the member's notes, shows nothing of its path in its own state: it is
95
+ # on it where a row that leads to it does, before its transaction or
96
+ # after it. The groups a through reaches by a `belongs_to` name those
97
+ # rows as `leads`.
74
98
  #: (Hash[Symbol, untyped], Hash[Symbol, untyped], untyped) -> Array[untyped]
75
99
  def join_versions(owners, group, reflection)
76
- path = ThroughPath.new(owners, reflection, @conditions)
77
100
  versions = group.fetch(:versions)
78
- return versions if path.open?
101
+ judge = @judge.call(owners, group, reflection)
102
+ return versions unless judge
79
103
 
80
- runs = versions.group_by { |version| join_run(version) }.values
81
- runs.select { |run| on_path?(group.fetch(:model), run, path) }.flat_map(&:itself)
104
+ versions.select { |version| judge.call(version) }
82
105
  end
83
106
 
84
107
  # Only the children the history loaded. Snapshots read children only under
@@ -97,13 +120,23 @@ module PaperTrailDiff
97
120
  historical_ids(child, ids, historical, range) | current
98
121
  end
99
122
 
100
- # The `belongs_to` targets each owner pointed at from the range's start
101
- # onward, plus the live row and those its recorded states name.
102
- #: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
103
- def target_rows(model, ids, reflection, range)
104
- historical, live = @targets[reflection] ||= target_candidates(model, reflection)
105
- eligible_rows(model, rows_for(historical, ids), range) + rows_for(live, ids) +
106
- recorded_target_rows(model, ids, reflection)
123
+ # The `belongs_to` targets each owner pointed at, as the states the
124
+ # history holds name them. PT-AT records a version's keys as they stood
125
+ # after its change, which is the state the record's next version stores,
126
+ # or its live row, and the history reads both; it also reads the state a
127
+ # key changed without a version, such as one `has_paper_trail only:`
128
+ # leaves out, reaches only through.
129
+ #: (untyped, Array[untyped], untyped) -> Array[TargetRow]
130
+ def target_rows(model, ids, reflection)
131
+ key = reflection.foreign_key
132
+ ids.flat_map do |id|
133
+ targets = @records.attribute_values_for(model, [id], key)
134
+ types = (@records.attribute_values_for(model, [id], reflection.foreign_type) if
135
+ reflection.polymorphic?) || []
136
+ targets.zip(types).filter_map do |target, type|
137
+ TargetRow.new(id, target, type) unless target.nil?
138
+ end
139
+ end
107
140
  end
108
141
 
109
142
  #: (untyped, untyped) -> bool
@@ -111,59 +144,12 @@ module PaperTrailDiff
111
144
  @records.loaded?(model, id)
112
145
  end
113
146
 
114
- # PT-AT records HABTM membership once per transaction, under the
115
- # association's name, so the rows are keyed by transaction id.
116
- #: (untyped, Array[untyped], untyped) -> Array[untyped]
117
- def habtm_rows(model, selected_versions, reflection)
118
- rows = @rows[reflection] ||= load_habtm_rows(model, reflection)
119
- transaction_ids(selected_versions).flat_map { |id| rows.fetch(id.to_s, []) }
120
- end
121
-
122
147
  private
123
148
 
124
149
  # @rbs @records: PreparedRecordIndex
125
- # @rbs @start_at: untyped
126
- # @rbs @roots: Hash[Array[String], Array[untyped]]
127
150
  # @rbs @nodes: Hash[String, Array[untyped]]
128
- # @rbs @targets: Hash[untyped, untyped]
129
- # @rbs @rows: Hash[untyped, Hash[String, Array[untyped]]]
130
151
  # @rbs @conditions: ScopeCondition::Cache
131
-
132
- # The versions one row saved in one transaction, or alone.
133
- #: (untyped) -> Array[untyped]
134
- def join_run(version)
135
- [version.item_id, ActivityTransactionGroups.transaction_key(version) || version]
136
- end
137
-
138
- # A run's versions are in the order they were saved, as the row's series
139
- # holds them.
140
- #: (untyped, Array[untyped], ThroughPath) -> bool
141
- def on_path?(model, run, path)
142
- first = run.fetch(0)
143
- @records.typed_states_across(model, first.item_id, first, run.fetch(-1))
144
- .any? { |attributes| path.include?(attributes) }
145
- end
146
-
147
- # The targets the owners' recorded states point at. PT-AT names a target
148
- # only in the rows its owner's versions wrote, so a key changed without a
149
- # version, such as one `has_paper_trail only:` leaves out, names its target
150
- # only in the state the owner's next version recorded. Prepared history
151
- # reads that state, so its snapshots show the target, and the target's
152
- # versions are events too. A key of two columns is read per record instead.
153
- #: (untyped, Array[untyped], untyped) -> Array[ActivityTargetCandidateLoader::Row]
154
- def recorded_target_rows(model, ids, reflection)
155
- key = reflection.foreign_key
156
- return [] if key.is_a?(Array)
157
-
158
- ids.flat_map do |id|
159
- targets = @records.attribute_values_for(model, [id], key)
160
- types = (@records.attribute_values_for(model, [id], reflection.foreign_type) if
161
- reflection.polymorphic?) || []
162
- targets.zip(types).filter_map do |target, type|
163
- ActivityTargetCandidateLoader::Row.new(id, target, type) unless target.nil?
164
- end
165
- end
166
- end
152
+ # @rbs @judge: JoinRunJudge
167
153
 
168
154
  #: (untyped, Array[untyped]) -> bool
169
155
  def member_class?(model, classes)
@@ -183,40 +169,18 @@ module PaperTrailDiff
183
169
  end
184
170
  end
185
171
 
172
+ # The records of a model the history holds, which every owner whose
173
+ # children are asked for is among.
186
174
  #: (untyped) -> Array[untyped]
187
175
  def node_ids(model)
188
- name = model.base_class.name
189
- @nodes.fetch(name) do
190
- raise ConfigurationError,
191
- "prepared activity graph is missing #{name}; " \
192
- 'register the model before collecting activity'
193
- end
194
- end
195
-
196
- #: (Hash[String, Array[ActivityTargetCandidateLoader::Row]], Array[untyped]) -> Array[ActivityTargetCandidateLoader::Row]
197
- def rows_for(grouped, ids)
198
- ids.flat_map { |id| grouped[id.to_s] || [] }
199
- end
200
-
201
- #: (untyped, Array[ActivityTargetCandidateLoader::Row], ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
202
- def eligible_rows(model, rows, range)
203
- rows.select do |row|
204
- eligible_version?(model, row.owner_id, row.created_at, row.event, range)
205
- end
206
- end
207
-
208
- #: (untyped, untyped) -> untyped
209
- def target_candidates(model, reflection)
210
- loader = ActivityTargetCandidateLoader.new(model, node_ids(model), reflection, @start_at)
211
- [loader.historical_rows.group_by { |row| row.owner_id.to_s },
212
- loader.current_rows.group_by { |row| row.owner_id.to_s }]
176
+ @nodes.fetch(model.base_class.name)
213
177
  end
214
178
 
215
179
  # Mirrors VersionAssociationCandidateScope's before-window rule. The loaded
216
180
  # series includes changes to other owners too, so an old membership cannot
217
181
  # survive a later pre-window reassignment just because that owner is absent.
218
182
  # A range starting at a version starts before that version's transaction,
219
- # as the scope's start does (see VersionBoundary.transaction_start), so a
183
+ # as the scope's start does (see TransactionCut.range_start), so a
220
184
  # membership that ended earlier in that transaction still held there. So
221
185
  # did one that the record's own transaction across the start ended.
222
186
  #: (untyped, untyped, untyped, String?, ActivityRange) -> bool
@@ -238,114 +202,182 @@ module PaperTrailDiff
238
202
  end
239
203
 
240
204
  # Whether every version of a record from `first` up to the start is one
241
- # of the transactions it saved a version in from the start onward.
205
+ # of a transaction that crossed the start: one the record saved a version
206
+ # in from the start onward, or one the history found crossing it by
207
+ # another record's versions. Such a transaction may have saved this
208
+ # record only before the start, as when it moved a comment away there
209
+ # and saved the comment's reply after it. The window before the start
210
+ # leaves that move to this one, which finds the reply only under the
211
+ # comment where it stood before the transaction.
242
212
  #: (Array[untyped], Integer, untyped) -> bool
243
213
  def crossed_start?(versions, first, start)
244
- after = versions.bsearch_index { |version| version.created_at >= start }
245
- return false unless after
246
-
214
+ after = versions.bsearch_index { |version| version.created_at >= start } || versions.length
215
+ later = versions.drop(after).map do |version|
216
+ ActivityTransactionGroups.transaction_key(version)
217
+ end
247
218
  versions.take(after).drop(first).all? do |version|
248
- transaction_id = VersionBoundary.transaction_id(version)
249
- transaction_id && versions.drop(after).any? do |other|
250
- VersionBoundary.transaction_id(other) == transaction_id
251
- end
219
+ key = ActivityTransactionGroups.transaction_key(version)
220
+ !key.nil? && later.include?(key)
252
221
  end
253
222
  end
223
+ end
254
224
 
255
- # Each statement reads the rows of 500 transactions.
256
- #: (untyped, untyped) -> Hash[String, Array[untyped]]
257
- def load_habtm_rows(model, reflection)
258
- rows = model.paper_trail.version_association_class.where(foreign_key_name: reflection.name)
259
- transaction_ids(versions(model, node_ids(model)))
260
- .each_slice(Support::IDS_PER_STATEMENT)
261
- .flat_map { |slice| rows.where(version_id: slice) }
262
- .group_by { |row| row.version_id.to_s }
225
+ # Whether one state of a through's join row puts it on the through's path.
226
+ # The row must join one of the owners as the join association reads it: by
227
+ # its key, by the owner's type under `as:`, by its class when the
228
+ # association is to a subclass, and by the association's scope when the
229
+ # gem can read it, unranked, as a through reads its parts. A through that
230
+ # goes through a belongs_to, or through another through, is joined by the
231
+ # owner's key or by rows further down, which a row's own state cannot
232
+ # show. Under `source_type:`, the row's type column must name that class;
233
+ # a version saved before the column existed has no type to read.
234
+ class ThroughPath
235
+ #: (Hash[Symbol, untyped], untyped, ScopeCondition::Cache) -> void
236
+ def initialize(owners, reflection, conditions)
237
+ @reflection = reflection
238
+ @through = reflection.through_reflection
239
+ @keyed = keyed?
240
+ @ids = owners.fetch(:ids).to_set(&:to_s)
241
+ @owner_type = @through.type && AssociationTraversal.owner_type(@through)
242
+ @conditions = conditions
263
243
  end
264
244
 
265
- # A version without a transaction id names no rows, so it can stay in.
266
- #: (Array[untyped]) -> Array[untyped]
267
- def transaction_ids(versions)
268
- versions.map { |version| VersionBoundary.transaction_id(version) }.uniq
245
+ # Whether every state of a row is on the path, so that none need be read.
246
+ #: () -> bool
247
+ def open?
248
+ !@keyed && @reflection.options[:source_type].nil?
269
249
  end
270
250
 
271
- # Whether one state of a through's join row puts it on the through's path.
272
- # The row must join one of the owners as the join association reads it: by
273
- # its key, by the owner's type under `as:`, by its class when the
274
- # association is to a subclass, and by the association's scope when the
275
- # gem can read it, unranked, as a through reads its parts. A through that
276
- # goes through a belongs_to, or through another through, is joined by the
277
- # owner's key or by rows further down, which a row's own state cannot
278
- # show. Under `source_type:`, the row's type column must name that class;
279
- # a version saved before the column existed has no type to read.
280
- class ThroughPath
281
- #: (Hash[Symbol, untyped], untyped, ScopeCondition::Cache) -> void
282
- def initialize(owners, reflection, conditions)
283
- @reflection = reflection
284
- @through = reflection.through_reflection
285
- @keyed = keyed?
286
- @ids = owners.fetch(:ids).to_set(&:to_s)
287
- @owner_types = owner_types(owners.fetch(:model))
288
- @conditions = conditions
289
- end
251
+ #: (Hash[untyped, untyped]) -> bool
252
+ def include?(attributes)
253
+ (!@keyed || joined?(attributes)) && typed?(attributes)
254
+ end
290
255
 
291
- # Whether every state of a row is on the path, so that none need be read.
292
- #: () -> bool
293
- def open?
294
- !@keyed && @reflection.options[:source_type].nil?
295
- end
256
+ private
296
257
 
297
- #: (Hash[untyped, untyped]) -> bool
298
- def include?(attributes)
299
- (!@keyed || joined?(attributes)) && typed?(attributes)
300
- end
258
+ # @rbs @reflection: untyped
259
+ # @rbs @through: untyped
260
+ # @rbs @keyed: bool
261
+ # @rbs @ids: Set[String]
262
+ # @rbs @owner_type: String?
263
+ # @rbs @conditions: ScopeCondition::Cache
301
264
 
302
- private
265
+ #: () -> bool
266
+ def keyed?
267
+ !@through.through_reflection? && !@through.belongs_to?
268
+ end
303
269
 
304
- # @rbs @reflection: untyped
305
- # @rbs @through: untyped
306
- # @rbs @keyed: bool
307
- # @rbs @ids: Set[String]
308
- # @rbs @owner_types: Array[String]?
309
- # @rbs @conditions: ScopeCondition::Cache
270
+ #: (Hash[untyped, untyped]) -> bool
271
+ def joined?(attributes)
272
+ @ids.include?(attributes.fetch(@through.foreign_key).to_s) && owner_type?(attributes) &&
273
+ AssociationTraversal.sti_member?(@through.klass, attributes) && in_scope?(attributes)
274
+ end
310
275
 
311
- #: () -> bool
312
- def keyed?
313
- !@through.through_reflection? && !@through.belongs_to? &&
314
- !@through.foreign_key.is_a?(Array)
315
- end
276
+ # An `as:` row's type column must hold its owner's polymorphic name.
277
+ #: (Hash[untyped, untyped]) -> bool
278
+ def owner_type?(attributes)
279
+ type = @owner_type
280
+ !type || type == attributes.fetch(@through.type)
281
+ end
316
282
 
317
- #: (Hash[untyped, untyped]) -> bool
318
- def joined?(attributes)
319
- @ids.include?(attributes.fetch(@through.foreign_key).to_s) && owner_type?(attributes) &&
320
- AssociationTraversal.sti_member?(@through.klass, attributes) && in_scope?(attributes)
321
- end
283
+ #: (Hash[untyped, untyped]) -> bool
284
+ def in_scope?(attributes)
285
+ condition = @conditions.call(@through, ranked: false)
286
+ !condition || condition.matches?(attributes)
287
+ end
322
288
 
323
- # The names an `as:` row's type column may hold for an owner.
324
- #: (untyped) -> Array[String]?
325
- def owner_types(model)
326
- return unless @through.type
289
+ # As the through's snapshots read a join row (see
290
+ # PreparedStateAssociationReader#typed_join?).
291
+ #: (Hash[untyped, untyped]) -> bool
292
+ def typed?(attributes)
293
+ AssociationTraversal.source_type_member?(@reflection, attributes[@reflection.foreign_type])
294
+ end
295
+ end
327
296
 
328
- [model.name, model.base_class.name, @through.active_record.name]
329
- end
297
+ # How the versions of a through's join row are judged (see
298
+ # PreparedActivityIndex#join_versions): by the row's own states, or by the
299
+ # rows that lead to it, or not at all. A version is judged by its whole
300
+ # transaction, so the row's versions in one transaction are judged alike.
301
+ class JoinRunJudge
302
+ #: (PreparedRecordIndex, ScopeCondition::Cache) -> void
303
+ def initialize(records, conditions)
304
+ @records = records
305
+ @conditions = conditions
306
+ end
330
307
 
331
- #: (Hash[untyped, untyped]) -> bool
332
- def owner_type?(attributes)
333
- types = @owner_types
334
- !types || types.include?(attributes.fetch(@through.type))
335
- end
308
+ #: (Hash[Symbol, untyped], Hash[Symbol, untyped], untyped) -> (^(untyped) -> bool)?
309
+ def call(owners, group, reflection)
310
+ model = group.fetch(:model)
311
+ path = ThroughPath.new(owners, reflection, @conditions)
312
+ return ->(version) { on_path?(model, version, path) } unless path.open?
336
313
 
337
- #: (Hash[untyped, untyped]) -> bool
338
- def in_scope?(attributes)
339
- condition = @conditions.call(@through, ranked: false)
340
- !condition || condition.matches?(attributes)
341
- end
314
+ leads = group[:leads]
315
+ return unless leads
316
+
317
+ lead = ThroughLead.new(@records, owners, leads, @conditions)
318
+ ->(version) { lead.include?(*transaction_span(model, version)) }
319
+ end
320
+
321
+ private
322
+
323
+ # @rbs @records: PreparedRecordIndex
324
+ # @rbs @conditions: ScopeCondition::Cache
325
+
326
+ #: (untyped, untyped, ThroughPath) -> bool
327
+ def on_path?(model, version, path)
328
+ first, last = transaction_span(model, version)
329
+ @records.typed_states_across(model, first.item_id, first, last)
330
+ .any? { |attributes| path.include?(attributes) }
331
+ end
342
332
 
343
- # As the through's snapshots read a join row (see
344
- # PreparedStateAssociationReader#typed_join?).
345
- #: (Hash[untyped, untyped]) -> bool
346
- def typed?(attributes)
347
- AssociationTraversal.source_type_member?(@reflection, attributes[@reflection.foreign_type])
333
+ # The first and last versions the row saved in the version's
334
+ # transaction: a version is judged by the row's whole transaction, not
335
+ # only the part inside the range. A window whose edge falls inside the transaction holds only
336
+ # some of the row's versions in it. Judged by its destroy alone, a row
337
+ # moved here and destroyed in one transaction was on the path, so the
338
+ # window after the edge reported the transaction, which the window before
339
+ # it, judging the row by both versions, reported too. The row's series
340
+ # holds the whole transaction: history crossed by one is read from where
341
+ # it began (see PreparedHistoryLoader#reload). A version saved outside a
342
+ # transaction is judged alone.
343
+ #: (untyped, untyped) -> [untyped, untyped]
344
+ def transaction_span(model, version)
345
+ key = ActivityTransactionGroups.transaction_key(version)
346
+ return [version, version] unless key
347
+
348
+ saved = @records.versions_for_id(model, version.item_id)
349
+ .select { |other| ActivityTransactionGroups.transaction_key(other) == key }
350
+ [saved.fetch(0), saved.fetch(-1)]
351
+ end
352
+ end
353
+
354
+ # Whether the rows that lead to a through's target, as a through over that
355
+ # through reads it, named the target before a transaction of the target's
356
+ # or after it, on their own path (see PreparedActivityIndex#join_versions).
357
+ class ThroughLead
358
+ #: (PreparedRecordIndex, Hash[Symbol, untyped], Hash[Symbol, untyped], ScopeCondition::Cache) -> void
359
+ def initialize(records, owners, leads, conditions)
360
+ @records = records
361
+ @rows = leads.fetch(:group)
362
+ reflection = leads.fetch(:reflection)
363
+ @path = ThroughPath.new(owners, reflection, conditions)
364
+ @key = reflection.foreign_key
365
+ end
366
+
367
+ # `first` and `last` are the target's versions that span its transaction.
368
+ #: (untyped, untyped) -> bool
369
+ def include?(first, last)
370
+ id = first.item_id.to_s
371
+ @rows.fetch(:ids).any? do |row|
372
+ @records.typed_states_around(@rows.fetch(:model), row, first, last).any? do |attributes|
373
+ attributes.fetch(@key).to_s == id && @path.include?(attributes)
374
+ end
348
375
  end
349
376
  end
377
+
378
+ # @rbs @records: PreparedRecordIndex
379
+ # @rbs @rows: Hash[Symbol, untyped]
380
+ # @rbs @path: ThroughPath
381
+ # @rbs @key: untyped
350
382
  end
351
383
  end
@@ -33,9 +33,11 @@ module PaperTrailDiff
33
33
  end
34
34
  end
35
35
 
36
- #: (untyped) -> void
37
- def initialize(start_at)
36
+ # `end_at` is where the history ends, if it does.
37
+ #: (untyped, ?untyped) -> void
38
+ def initialize(start_at, end_at = nil)
38
39
  @start_at = start_at
40
+ @end_at = end_at
39
41
  @read = {} #: Hash[Array[untyped], Read]
40
42
  end
41
43
 
@@ -47,12 +49,20 @@ module PaperTrailDiff
47
49
  read = @read[[model, reflection]] ||= Read.new
48
50
  unless read.unread(ids).empty?
49
51
  owners = read.unread(block_given? ? yield | ids : ids)
50
- read.add(owners, ActivityChildCandidateLoader.new(model, owners, reflection, @start_at))
52
+ read.add(owners, loader(model, owners, reflection))
51
53
  end
52
54
  [read.historical, read.live]
53
55
  end
54
56
 
57
+ private
58
+
59
+ #: (untyped, Array[untyped], untyped) -> ActivityChildCandidateLoader
60
+ def loader(model, owners, reflection)
61
+ ActivityChildCandidateLoader.new(model, owners, reflection, @start_at, @end_at)
62
+ end
63
+
55
64
  # @rbs @start_at: untyped
65
+ # @rbs @end_at: untyped
56
66
  # @rbs @read: Hash[Array[untyped], Read]
57
67
  end
58
68
  end
@@ -6,34 +6,27 @@ module PaperTrailDiff
6
6
  class PreparedEdgeLoader
7
7
  # A history shares `children` with its activity index, which reads the
8
8
  # children this finds again.
9
- #: (PreparedRecordIndex, Array[untyped], ?start_at: untyped, ?children: PreparedChildCandidates) -> void
10
- def initialize(records, root_versions, start_at: root_versions.first&.created_at,
11
- children: PreparedChildCandidates.new(start_at))
9
+ #: (PreparedRecordIndex, children: PreparedChildCandidates) -> void
10
+ def initialize(records, children:)
12
11
  @records = records
13
- @transaction_ids = root_versions.filter_map(&:transaction_id)
14
12
  @children = children
15
13
  end
16
14
 
17
- # HABTM alone also returns each root transaction's members.
18
- #: (untyped, Array[untyped], untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]?]
15
+ #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
19
16
  def call(owner_class, owner_ids, reflection)
20
- case reflection.macro
21
- when :belongs_to then [belongs_to_groups(owner_class, owner_ids, reflection), nil]
22
- when :has_and_belongs_to_many then habtm_groups(owner_class, reflection)
23
- else [child_groups(owner_class, owner_ids, reflection), nil]
24
- end
17
+ return belongs_to_groups(owner_class, owner_ids, reflection) if reflection.belongs_to?
18
+
19
+ child_groups(owner_class, owner_ids, reflection)
25
20
  end
26
21
 
27
22
  private
28
23
 
29
24
  # @rbs @records: PreparedRecordIndex
30
- # @rbs @transaction_ids: Array[untyped]
31
25
  # @rbs @children: PreparedChildCandidates
32
26
 
33
27
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
34
28
  def belongs_to_groups(owner_class, owner_ids, reflection)
35
- key = AssociationKey.scalar_foreign_key(reflection)
36
- return {} unless key
29
+ key = reflection.foreign_key
37
30
  return polymorphic_groups(owner_class, owner_ids, reflection, key) if reflection.polymorphic?
38
31
 
39
32
  group_for(reflection.klass, @records.attribute_values_for(owner_class, owner_ids, key))
@@ -44,10 +37,10 @@ module PaperTrailDiff
44
37
  #: (untyped, Array[untyped], untyped, String) -> Hash[String, Hash[Symbol, untyped]]
45
38
  def polymorphic_groups(owner_class, owner_ids, reflection, key)
46
39
  grouped = {} #: Hash[String, Hash[Symbol, untyped]]
47
- @records.records_for(owner_class, owner_ids).each do |owner|
48
- id = owner.public_send(key)
49
- type = owner.public_send(reflection.foreign_type).to_s
50
- model_class = AssociationTraversal.named_class(type)
40
+ ids = @records.attribute_values_for(owner_class, owner_ids, key)
41
+ types = @records.attribute_values_for(owner_class, owner_ids, reflection.foreign_type)
42
+ ids.zip(types) do |id, type|
43
+ model_class = AssociationTraversal.named_class(type.to_s)
51
44
  add_identity(grouped, model_class, id) if model_class && id
52
45
  end
53
46
  grouped.transform_values { |group| group.merge(ids: group.fetch(:ids).uniq) }
@@ -65,37 +58,6 @@ module PaperTrailDiff
65
58
  group_for(reflection.klass, owners.values.flatten, owners: owners)
66
59
  end
67
60
 
68
- # A transaction more than one owner recorded members in is left out, so
69
- # its read falls back to HistoricalAssociationReifier, which raises.
70
- #: (untyped, untyped) -> [Hash[String, Hash[Symbol, untyped]], Hash[String, Array[untyped]]]
71
- def habtm_groups(owner_class, reflection)
72
- rows = habtm_rows(owner_class, reflection)
73
- recorded = rows.group_by { |row| row.version_id.to_s }
74
- shared = HabtmTransactionOwners.new(owner_class, reflection).shared(recorded.keys)
75
- [group_for(reflection.klass, rows.map(&:foreign_key_id)),
76
- memberships(recorded).except(*shared)]
77
- end
78
-
79
- # Each root transaction's members, from its rows grouped by transaction.
80
- #: (Hash[String, Array[untyped]]) -> Hash[String, Array[untyped]]
81
- def memberships(recorded)
82
- empty = [] #: Array[untyped]
83
- @transaction_ids.to_h do |transaction_id|
84
- key = transaction_id.to_s
85
- [key, recorded.fetch(key, empty).map(&:foreign_key_id)]
86
- end
87
- end
88
-
89
- # Each statement reads up to 500 of the root transactions: SQL Server
90
- # compiles a long list of ids slowly.
91
- #: (untyped, untyped) -> Array[untyped]
92
- def habtm_rows(owner_class, reflection)
93
- associations = owner_class.paper_trail.version_association_class
94
- @transaction_ids.uniq.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
95
- associations.where(version_id: slice, foreign_key_name: reflection.name)
96
- end
97
- end
98
-
99
61
  #: (Hash[String, Hash[Symbol, untyped]], untyped, untyped) -> void
100
62
  def add_identity(groups, model_class, id)
101
63
  group = groups[model_class.name.to_s] ||= { model: model_class, ids: [] }