paper_trail_diff 0.17.1 → 0.18.1

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 +661 -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 +195 -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 +126 -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
@@ -20,11 +20,6 @@ module PaperTrailDiff
20
20
  @owner = reflection.active_record
21
21
  end
22
22
 
23
- #: () -> bool
24
- def available?
25
- !@reflection.foreign_key.is_a?(Array)
26
- end
27
-
28
23
  #: (untyped) -> untyped
29
24
  def relation(_filter)
30
25
  raise NotImplementedError, "#{self.class} must build its relation"
@@ -52,12 +47,6 @@ module PaperTrailDiff
52
47
  model.type_for_attribute(name).type
53
48
  end
54
49
 
55
- # A relation is compared as its SQL; ids are compared as values.
56
- #: (untyped) -> untyped
57
- def arel_value(filter)
58
- filter.respond_to?(:arel) ? filter.arel : filter
59
- end
60
-
61
50
  # The owners a child pointed at when the window opened or after a change
62
51
  # inside it, as PT-AT recorded them on the child's own versions.
63
52
  class Child < AssociationActivityEdge
@@ -88,8 +77,106 @@ module PaperTrailDiff
88
77
 
89
78
  #: () -> Array[String?]
90
79
  def owner_types
91
- [nil, '', @owner.name, @owner.base_class.name]
80
+ RecordedOwner.types(@reflection, @owner)
81
+ end
82
+ end
83
+
84
+ # The owners of children no version was ever saved for, such as rows from
85
+ # before PaperTrail: such a child has held its live key throughout, as an
86
+ # analysis reads it, and so leads to a change further down.
87
+ class Unversioned < AssociationActivityEdge
88
+ #: (untyped, TimeRange?) -> void
89
+ def initialize(reflection, time_range)
90
+ super
91
+ @target = reflection.klass
92
+ @versions = @target.paper_trail.version_class
93
+ @key = @target.primary_key
94
+ @column = @target.arel_table[reflection.foreign_key]
95
+ @type = column_type(@target, reflection.foreign_key)
96
+ @filter_type = column_type(@target, @key)
97
+ end
98
+
99
+ #: (untyped) -> untyped
100
+ def relation(filter)
101
+ rows = @target.unscoped.where(@key => filter)
102
+ type = @reflection.type
103
+ held = { type => @owner.polymorphic_name } #: Hash[untyped, untyped]
104
+ rows = rows.where(held) if type
105
+ comparable? ? rows.where(versioned.not) : rows.where.not(@key => versioned_ids(rows))
106
+ end
107
+
108
+ private
109
+
110
+ # @rbs @target: untyped
111
+ # @rbs @versions: untyped
112
+ # @rbs @key: String
113
+
114
+ # A database compares the key with item_id only when they share a type.
115
+ #: () -> bool
116
+ def comparable?
117
+ column_type(@versions, 'item_id') == @filter_type
118
+ end
119
+
120
+ #: () -> untyped
121
+ def versioned
122
+ table = @versions.arel_table
123
+ VersionQuery.for_model(@target).where(table[:item_id].eq(@target.arel_table[@key]))
124
+ .arel.exists
125
+ end
126
+
127
+ # The keys of the rows that have versions, read as values; a database
128
+ # casts them back to the key's type.
129
+ #: (untyped) -> Array[untyped]
130
+ def versioned_ids(rows)
131
+ VersionQuery.for_items(@target, rows.pluck(@key)).distinct.pluck(:item_id)
132
+ end
133
+ end
134
+
135
+ # The owners of children whose first version since the window opened did
136
+ # not create them, such as rows from before PaperTrail that the window
137
+ # moves or detaches. PT-AT stores the keys a version saved, so the owner
138
+ # such a child held until that version is in no row, only in the
139
+ # version's stored state, as ActivityChildCandidateLoader reads it. One
140
+ # saved after the window's end holds the owner the child had there too.
141
+ class FirstVersion < AssociationActivityEdge
142
+ #: (untyped, TimeRange?) -> void
143
+ def initialize(reflection, time_range)
144
+ super
145
+ @target = reflection.klass
146
+ @filter_type = column_type(@target.paper_trail.version_class, 'item_id')
147
+ end
148
+
149
+ # A create stores no state, so the first versions read are those that
150
+ # did not create their child.
151
+ #: (untyped) -> untyped
152
+ def relation(filter)
153
+ relation = VersionQuery.for_model(@target).where(item_id: filter).where.not(object: nil)
154
+ versions = relation.arel_table
155
+ relation = relation.where(VersionQuery.no_earlier_version(versions))
156
+ start = @time_range&.begin_time
157
+ start ? relation.where(versions[:created_at].gteq(start)) : relation
158
+ end
159
+
160
+ # The owners the first versions of the children `filter` selects name in
161
+ # their stored states. An `as:` child's type must name one of the
162
+ # owner's types, which take a child with no type, as any plain child has.
163
+ # A version with no state for the key names no owner.
164
+ #: (untyped) -> Array[untyped]
165
+ def owners(filter)
166
+ types = RecordedOwner.types(@reflection, @owner)
167
+ relation(filter).select(:object).filter_map do |version|
168
+ state = version.object_deserialized
169
+ state[@reflection.foreign_key] if types.include?(state[@reflection.type])
170
+ end
171
+ end
172
+
173
+ # The same for children's ids read as values, in slices.
174
+ #: (Array[untyped]) -> Array[untyped]
175
+ def owners_of(ids)
176
+ ids.each_slice(Support::IDS_PER_STATEMENT).flat_map { |slice| owners(slice) }
92
177
  end
178
+
179
+ # @rbs @target: untyped
93
180
  end
94
181
 
95
182
  # The owners that pointed at a target when the window opened or after a
@@ -140,78 +227,5 @@ module PaperTrailDiff
140
227
  .where(@versions.table_name => { item_type: @owner.base_class.name })
141
228
  end
142
229
  end
143
-
144
- # The owners a HABTM join row links to a target now. A join table has no
145
- # model to type its columns, so the owner column is read by quoted name.
146
- class LiveHabtm < AssociationActivityEdge
147
- #: (untyped, TimeRange?) -> void
148
- def initialize(reflection, time_range)
149
- super
150
- @table = Support.arel::Table.new(reflection.join_table)
151
- columns = join_columns
152
- @type = columns.fetch(reflection.foreign_key)
153
- @filter_type = columns.fetch(reflection.association_foreign_key)
154
- @column = quoted_owner_column
155
- end
156
-
157
- #: (untyped) -> untyped
158
- def relation(filter)
159
- target = @table[@reflection.association_foreign_key]
160
- @owner.base_class.unscoped.from(@table).where(target.in(arel_value(filter)))
161
- end
162
-
163
- private
164
-
165
- # @rbs @table: untyped
166
-
167
- #: () -> Hash[String, Symbol?]
168
- def join_columns
169
- Support.with_connection(@owner) do |connection|
170
- connection.columns(@reflection.join_table).to_h { |column| [column.name, column.type] }
171
- end
172
- end
173
-
174
- # Some adapters take the quoted name as a plain string too, but a raw SQL
175
- # check may not, so it is marked as SQL; no SQLite spec can tell.
176
- # mutant:disable
177
- #: () -> untyped
178
- def quoted_owner_column
179
- Support.with_connection(@owner) do |connection|
180
- Support.arel.sql("#{connection.quote_table_name(@reflection.join_table)}." \
181
- "#{connection.quote_column_name(@reflection.foreign_key)}")
182
- end
183
- end
184
- end
185
-
186
- # The owners whose versions PT-AT recorded a HABTM target with, keyed by
187
- # the transaction each version was saved in.
188
- class RecordedHabtm < AssociationActivityEdge
189
- #: (untyped, TimeRange?) -> void
190
- def initialize(reflection, time_range)
191
- super
192
- @versions = @owner.paper_trail.version_class
193
- @associations = @owner.paper_trail.version_association_class
194
- @column = @versions.arel_table[:item_id]
195
- @type = column_type(@versions, 'item_id')
196
- @filter_type = column_type(@associations, 'foreign_key_id')
197
- end
198
-
199
- #: () -> bool
200
- def available?
201
- @versions.column_names.include?('transaction_id')
202
- end
203
-
204
- #: (untyped) -> untyped
205
- def relation(filter)
206
- transactions = @associations.where(foreign_key_name: @reflection.name,
207
- foreign_key_id: filter).select(:version_id)
208
- relation = @versions.where(item_type: @owner.base_class.name, transaction_id: transactions)
209
- range = @time_range
210
- range ? relation.where(created_at: range.begin_time..) : relation
211
- end
212
-
213
- # @rbs @versions: untyped
214
- # @rbs @associations: untyped
215
- end
216
230
  end
217
231
  end
@@ -37,10 +37,16 @@ module PaperTrailDiff
37
37
  @relation.distinct.pluck(@column).compact
38
38
  end
39
39
 
40
- # The ids with no match in `keys`, a subquery of the keys that exist.
40
+ # The ids no row of the model has for its key, whatever scope the model
41
+ # has by default. They are asked for with NOT EXISTS: PostgreSQL does
42
+ # not plan `NOT IN (SELECT ...)` as an anti-join, so it reads every key
43
+ # of the table for the statement, and again for each id once the keys
44
+ # outgrow its working memory. An empty key names no record.
41
45
  #: (untyped) -> Array[untyped]
42
- def missing(keys)
43
- @relation.where(@column.not_in(keys)).distinct.pluck(@column)
46
+ def missing(model)
47
+ key = model.arel_table[model.primary_key]
48
+ rows = model.unscoped.where(key.eq(@column)).arel.exists
49
+ @relation.where(rows.not).distinct.pluck(@column).compact
44
50
  end
45
51
  end
46
52
 
@@ -53,12 +59,24 @@ module PaperTrailDiff
53
59
  sources.flat_map { |ids| ids.is_a?(Query) ? ids.values : ids }.uniq
54
60
  end
55
61
 
62
+ # The window roots are selected over: the one asked for, and with a tree,
63
+ # from where the earliest transaction open at its start began (see
64
+ # SelectionWindow). A window reports such a transaction, which may have
65
+ # saved a root's tree only before it.
66
+ #: (untyped, AssociationTraversal?, TimeRange?) -> TimeRange?
67
+ def self.window(model, traversal, range)
68
+ return range unless range && traversal
69
+
70
+ reach = traversal.reach_before(model, range.begin_time)
71
+ reach ? SelectionWindow.new(range, reach) : range
72
+ end
73
+
56
74
  # Only the versions `version_scope` keeps select a root, on its
57
75
  # associations as on its own versions.
58
- #: (untyped, tree: AssociationTree, time_range: TimeRange?, ?version_scope: untyped) -> void
59
- def initialize(model, tree:, time_range:, version_scope: nil)
76
+ #: (untyped, traversal: AssociationTraversal, time_range: TimeRange?, ?version_scope: untyped) -> void
77
+ def initialize(model, traversal:, time_range:, version_scope: nil)
60
78
  @model = model
61
- @traversal = AssociationTraversal.new(tree)
79
+ @traversal = traversal
62
80
  @time_range = time_range
63
81
  @version_scope = version_scope
64
82
  end
@@ -95,7 +113,22 @@ module PaperTrailDiff
95
113
  return [] if ids.empty?
96
114
  return through_owners(reflection, ids) if reflection.through_reflection?
97
115
 
98
- edges(reflection).flat_map { |edge| follow(edge, ids) }
116
+ edges(reflection).flat_map { |edge| follow(edge, ids) } + first_owners(reflection, ids)
117
+ end
118
+
119
+ # The owners children held until a first version that did not create
120
+ # them, read from those versions' stored states (see
121
+ # AssociationActivityEdge::FirstVersion).
122
+ #: (untyped, Array[source]) -> Array[source]
123
+ def first_owners(reflection, ids)
124
+ return [] if reflection.belongs_to?
125
+
126
+ edge = AssociationActivityEdge::FirstVersion.new(reflection, @time_range)
127
+ found = ids.flat_map do |source|
128
+ query = subquery(source, edge.filter_type)
129
+ query ? edge.owners(query.relation) : edge.owners_of(self.class.values([source]))
130
+ end.uniq
131
+ found.empty? ? [] : [found]
99
132
  end
100
133
 
101
134
  # A join row that changes moves membership as surely as a target that does.
@@ -133,13 +166,12 @@ module PaperTrailDiff
133
166
 
134
167
  #: (untyped) -> Array[AssociationActivityEdge]
135
168
  def edges(reflection)
136
- kinds = case reflection.macro
137
- when :belongs_to then [AssociationActivityEdge::BelongsTo]
138
- when :has_and_belongs_to_many
139
- [AssociationActivityEdge::LiveHabtm, AssociationActivityEdge::RecordedHabtm]
140
- else [AssociationActivityEdge::Child]
169
+ kinds = if reflection.belongs_to?
170
+ [AssociationActivityEdge::BelongsTo]
171
+ else
172
+ [AssociationActivityEdge::Child, AssociationActivityEdge::Unversioned]
141
173
  end
142
- kinds.map { |kind| kind.new(reflection, @time_range) }.select(&:available?)
174
+ kinds.map { |kind| kind.new(reflection, @time_range) }
143
175
  end
144
176
 
145
177
  # Records with a version in the window, or only those of them `item_ids`
@@ -152,7 +184,7 @@ module PaperTrailDiff
152
184
  relation = item_ids ? VersionQuery.for_items(model, item_ids) : VersionQuery.for_model(model)
153
185
  range = @time_range
154
186
  relation = range.scope(relation) if range
155
- relation = @version_scope.call(relation) if @version_scope
187
+ relation = VersionScopeFilter.whole_transactions(@version_scope, relation) if @version_scope
156
188
  [Query.new(relation, versions.arel_table[:item_id],
157
189
  versions.type_for_attribute('item_id').type)]
158
190
  end
@@ -62,7 +62,7 @@ module PaperTrailDiff
62
62
 
63
63
  #: (untyped, prefix: String, ancestry: Array[untyped], depth: Integer) -> Array[AssociationDescriptor]
64
64
  def discover(model_class, prefix:, ancestry:, depth:)
65
- supported_reflections(model_class, root: prefix.empty?).flat_map do |reflection|
65
+ supported_reflections(model_class).flat_map do |reflection|
66
66
  describe_and_descend(reflection, prefix: prefix, ancestry: ancestry, depth: depth)
67
67
  end
68
68
  end
@@ -99,10 +99,10 @@ module PaperTrailDiff
99
99
  end
100
100
 
101
101
  # Only what a request accepts, so every listed path can be requested.
102
- #: (untyped, root: bool) -> Array[untyped]
103
- def supported_reflections(model_class, root:)
102
+ #: (untyped) -> Array[untyped]
103
+ def supported_reflections(model_class)
104
104
  reflections = model_class.reflect_on_all_associations.reject do |reflection|
105
- AssociationTraversal.unsupported_reason(model_class, reflection, root: root) ||
105
+ AssociationTraversal.unsupported_reason(model_class, reflection) ||
106
106
  unversioned?(reflection)
107
107
  end
108
108
  reflections.sort_by { |reflection| reflection.name.to_s }
@@ -5,12 +5,20 @@ module PaperTrailDiff
5
5
  # PT-AT records which record a child pointed at by that record's id, and
6
6
  # history matches children to owners and targets by id. An association
7
7
  # keyed on another column (`primary_key:`) would read other records'
8
- # history, so it is refused.
8
+ # history, and one keyed on several columns has no single id to match, so
9
+ # both are refused.
9
10
  module AssociationKey
10
11
  # Why the association, or a part of a through, cannot be read by id.
11
12
  #: (untyped) -> String?
12
13
  def self.unsupported_reason(reflection)
13
- part = keyed_part(reflection)
14
+ parts = [reflection, *AssociationTraversal.through_parts(reflection)]
15
+ composite = parts.find { |part| part.foreign_key.is_a?(Array) }
16
+ if composite
17
+ return "#{composite.active_record.name}##{composite.name} has a composite foreign " \
18
+ 'key, and association history is recorded by a single id'
19
+ end
20
+
21
+ part = parts.find { |candidate| other_key?(candidate) }
14
22
  return unless part
15
23
 
16
24
  "#{part.active_record.name}##{part.name} matches records by " \
@@ -18,22 +26,6 @@ module PaperTrailDiff
18
26
  'history is recorded by primary key'
19
27
  end
20
28
 
21
- # The association's foreign key column, or nil for a composite key, which
22
- # loaded history cannot index. Active Record names a column as a string.
23
- #: (untyped) -> String?
24
- def self.scalar_foreign_key(reflection)
25
- key = reflection.foreign_key
26
- key unless key.is_a?(Array)
27
- end
28
-
29
- # The reflection, or the first part of a through, keyed on a column other
30
- # than its owner's or target's primary key.
31
- #: (untyped) -> untyped
32
- def self.keyed_part(reflection)
33
- [reflection, *AssociationTraversal.through_parts(reflection)].find { |part| other_key?(part) }
34
- end
35
- private_class_method :keyed_part
36
-
37
29
  # A belongs_to names a key of its target; any other macro, one of its
38
30
  # owner. A polymorphic target has no single primary key to compare with.
39
31
  #: (untyped) -> bool
@@ -4,6 +4,10 @@
4
4
  module PaperTrailDiff
5
5
  # Resolves and validates ActiveRecord reflections for a bounded association tree.
6
6
  class AssociationTraversal # rubocop:disable Metrics/ClassLength
7
+ # A join table has no versions, so its rows' history cannot be read.
8
+ HABTM_REASON = 'a has_and_belongs_to_many keeps no history of its join rows; ' \
9
+ 'replace it with a has_many :through a join model that has has_paper_trail'
10
+
7
11
  # The class a `belongs_to` points at for this record, reading a polymorphic
8
12
  # type column when there is one. Nil when the record points at nothing.
9
13
  #: (untyped, untyped) -> untyped
@@ -14,6 +18,16 @@ module PaperTrailDiff
14
18
  polymorphic_target(reflection, record, type) unless type.empty?
15
19
  end
16
20
 
21
+ # Whether an unordered has_one through reads the target of its first
22
+ # join row. SQL Server plans the join from the target's table instead, so
23
+ # its LIMIT reads the target with the lowest key, as a plain has_one does.
24
+ #: (untyped) -> bool
25
+ def self.join_order?(reflection)
26
+ return false if reflection.active_record.connection_db_config.adapter == 'sqlserver'
27
+
28
+ reflection.through_reflection?
29
+ end
30
+
17
31
  # A through with `source_type:` reaches only the join records whose type
18
32
  # column names that class, as Active Record's `where(type => source_type)`.
19
33
  # A through's `foreign_type` is its polymorphic source's.
@@ -62,33 +76,41 @@ module PaperTrailDiff
62
76
  named_class(type.to_s)
63
77
  end
64
78
 
79
+ # The type an `as:` child stores for its owner. Active Record reads only
80
+ # this one, its owner's polymorphic name, which an STI subclass shares
81
+ # with its base class; a child typed with a subclass's name is no member.
82
+ # The declaring class shares the owner's base class, so it names it.
83
+ #: (untyped) -> String
84
+ def self.owner_type(reflection)
85
+ reflection.active_record.polymorphic_name
86
+ end
87
+
65
88
  # A type left by a renamed or removed model names no class. Active Record
66
89
  # and PT-AT raise a bare NameError for it, which does not say where it is.
67
90
  #: (untyped, untyped, String) -> untyped
68
91
  def self.polymorphic_target(reflection, record, type)
69
- model_class = named_class(type)
70
- return model_class if model_class
92
+ named_class(type) || unnamed_target!(reflection, record.class, record.id, type)
93
+ end
94
+ private_class_method :polymorphic_target
71
95
 
96
+ #: (untyped, untyped, untyped, untyped) -> bot
97
+ def self.unnamed_target!(reflection, owner_class, id, type)
72
98
  raise IncompleteAssociationHistoryError,
73
- "association #{record.class.name}##{reflection.name} cannot be read: " \
74
- "#{record.class.name} #{record.id} has #{reflection.foreign_type} #{type}, which " \
99
+ "association #{owner_class.name}##{reflection.name} cannot be read: " \
100
+ "#{owner_class.name} #{id} has #{reflection.foreign_type} #{type}, which " \
75
101
  'names no class. If the model was renamed, replace the old name in that column ' \
76
102
  'and in the versions that recorded it.'
77
103
  end
78
- private_class_method :polymorphic_target
79
104
 
80
105
  # Why a request cannot name this association of the model, or nil when it
81
- # can; `root` says whether the model is the record the request compares.
82
- # Discovery lists only the associations this accepts, so every path it
83
- # lists can be requested. A has_many :through Active Record cannot follow
84
- # raises Active Record's own error.
85
- #: (untyped, untyped, root: bool) -> String?
86
- def self.unsupported_reason(model_class, reflection, root:)
106
+ # can. Discovery lists only the associations this accepts, so every path
107
+ # it lists can be requested. A has_many :through Active Record cannot
108
+ # follow raises Active Record's own error.
109
+ #: (untyped, untyped) -> String?
110
+ def self.unsupported_reason(model_class, reflection)
87
111
  return 'PaperTrail versions' if paper_trail_versions?(model_class, reflection)
112
+ return HABTM_REASON if reflection.macro == :has_and_belongs_to_many
88
113
  return reflection.macro.to_s unless SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro)
89
- if reflection.macro == :has_and_belongs_to_many
90
- return habtm_reason(reflection, root) || VersionTable.unsupported_reason(reflection)
91
- end
92
114
 
93
115
  habtm = habtm_in_chain(reflection)
94
116
  return storage_reason(reflection) unless habtm
@@ -97,40 +119,15 @@ module PaperTrailDiff
97
119
  'whose hidden join model has no history to compare'
98
120
  end
99
121
 
100
- # History matches records by primary key, within one set of version tables.
122
+ # History matches records by primary key, within one set of version
123
+ # tables, and finds a child's owner where the child's versions recorded it.
101
124
  #: (untyped) -> String?
102
125
  def self.storage_reason(reflection)
103
- AssociationKey.unsupported_reason(reflection) || VersionTable.unsupported_reason(reflection)
126
+ AssociationKey.unsupported_reason(reflection) ||
127
+ VersionTable.unsupported_reason(reflection) || RecordedOwner.unsupported_reason(reflection)
104
128
  end
105
129
  private_class_method :storage_reason
106
130
 
107
- # PT-AT records a HABTM's membership only when its owner saves a version,
108
- # in rows keyed by transaction and association name, not by owner. A root
109
- # checkpoint so holds the root's membership and no one else's: another
110
- # record's HABTM would read the root's rows, or none.
111
- #: (untyped) -> String
112
- def self.habtm_below_root(reflection)
113
- "#{reflection.active_record.name}##{reflection.name} is a has_and_belongs_to_many " \
114
- 'below the root, and a root checkpoint records HABTM membership for the root alone'
115
- end
116
- private_class_method :habtm_below_root
117
-
118
- # PT-AT records a HABTM's membership by loading the association, scope and
119
- # target default scope applied, so a target outside the scope when the
120
- # owner saved is never recorded. One that enters it before the next save
121
- # is a member then that history cannot hold.
122
- #: (untyped, bool) -> String?
123
- def self.habtm_reason(reflection, root)
124
- return habtm_below_root(reflection) unless root
125
- return unless ScopeCondition.scoped?(reflection)
126
-
127
- "#{reflection.active_record.name}##{reflection.name} is a scoped " \
128
- 'has_and_belongs_to_many, and PaperTrail records only the members its scope ' \
129
- 'admitted when the owner saved, so membership between saves cannot be rebuilt; ' \
130
- 'replace it with a has_many :through a versioned join model'
131
- end
132
- private_class_method :habtm_reason
133
-
134
131
  #: (untyped, untyped) -> bool
135
132
  def self.paper_trail_versions?(model_class, reflection)
136
133
  model_class.respond_to?(:versions_association_name) &&
@@ -179,7 +176,21 @@ module PaperTrailDiff
179
176
  def initialize(tree)
180
177
  @tree = tree
181
178
  @reflection_cache = {}
182
- @habtm_paths = {} #: Hash[untyped, Array[String]]
179
+ @reaches = {} #: Hash[[untyped, untyped], untyped]
180
+ end
181
+
182
+ # Where the earliest transaction open at `start` began, in the version
183
+ # tables of the model and of the records on its paths; nil when none was
184
+ # open, without a start, or without paths (see CrossingTransactions). A
185
+ # call reads every root of a model from one answer, so it is asked once.
186
+ #: (untyped, untyped) -> untyped
187
+ def reach_before(model_class, start)
188
+ return if @tree.empty? || start.nil?
189
+
190
+ key = [model_class, start] #: [untyped, untyped]
191
+ @reaches.fetch(key) do
192
+ @reaches[key] = CrossingTransactions.open_around(model_class, self, start)
193
+ end
183
194
  end
184
195
 
185
196
  #: (untyped) -> void
@@ -195,50 +206,26 @@ module PaperTrailDiff
195
206
  # The names the versions of the records on the requested paths are stored
196
207
  # under: each association's class and every part a through passes. A
197
208
  # polymorphic belongs_to names its target's class only in each record, so
198
- # it adds none.
209
+ # it adds none (see #polymorphic_paths?).
199
210
  #: (untyped) -> Array[String]
200
211
  def path_types(model_class)
201
- selected_reflections(model_class).flat_map do |_path, reflection|
202
- parts = [reflection, *self.class.through_parts(reflection)].reject(&:polymorphic?)
203
- parts.map { |part| part.klass.base_class.name }
204
- end.uniq
212
+ path_parts(model_class).reject(&:polymorphic?).map { |part| part.klass.base_class.name }.uniq
205
213
  end
206
214
 
207
- #: (untyped, untyped) -> void
208
- def ensure_habtm_history!(model_class, version)
209
- paths = habtm_paths(model_class)
210
- return if paths.empty?
211
- return if VersionBoundary.transaction_id(version)
212
-
213
- message = "HABTM history is incomplete at version #{version.id}: #{paths.join(', ')}"
214
- raise IncompleteAssociationHistoryError, message
215
+ # Whether a path passes a polymorphic belongs_to, whose targets may be of
216
+ # any class.
217
+ #: (untyped) -> bool
218
+ def polymorphic_paths?(model_class)
219
+ path_parts(model_class).any?(&:polymorphic?)
215
220
  end
216
221
 
217
- # Every snapshot of a version asks, so each class's answer is kept; the
218
- # tree and the class decide it. Reading it again each time answers the
219
- # same, which is why mutant leaves the cache alone.
220
- # mutant:disable
221
- #: (untyped) -> Array[String]
222
- def habtm_paths(model_class)
223
- @habtm_paths.fetch(model_class) do
224
- selected = selected_reflections(model_class)
225
- @habtm_paths[model_class] = selected.filter_map do |path, reflection|
226
- path if habtm_reflection?(reflection)
227
- end.freeze
222
+ #: (untyped) -> Array[untyped]
223
+ def path_parts(model_class)
224
+ selected_reflections(model_class).flat_map do |_path, reflection|
225
+ [reflection, *self.class.through_parts(reflection)]
228
226
  end
229
227
  end
230
-
231
- # HABTM join rows have no versions of their own, so membership changes
232
- # cannot be split into events once a range runs past the last root version
233
- # into live state.
234
- #: (untyped) -> void
235
- def reject_live_habtm_activity!(model_class)
236
- paths = habtm_paths(model_class)
237
- return if paths.empty?
238
-
239
- message = "live-ended activity cannot reconstruct HABTM event boundaries: #{paths.join(', ')}"
240
- raise UnsupportedLiveActivityError, message
241
- end
228
+ private :path_parts
242
229
 
243
230
  # A model and a tree resolve to the same reflections wherever they are
244
231
  # read: a tree is only ever walked from one place, the root tree at the
@@ -258,14 +245,13 @@ module PaperTrailDiff
258
245
  direct = %i[has_one has_many].include?(reflection.macro) && !reflection.through_reflection?
259
246
  return [] unless direct
260
247
 
261
- Array(reflection.foreign_key) + Array(reflection.type)
248
+ [reflection.foreign_key, *reflection.type]
262
249
  end
263
250
 
264
251
  private
265
252
 
266
253
  # @rbs @tree: AssociationTree
267
254
  # @rbs @reflection_cache: Hash[AssociationTree, Hash[untyped, Array[untyped]]]
268
- # @rbs @habtm_paths: Hash[untyped, Array[String]]
269
255
 
270
256
  #: (untyped, AssociationTree, path: String) -> Array[Array[untyped]]
271
257
  def collect_reflections(model_class, tree, path:)
@@ -306,25 +292,19 @@ module PaperTrailDiff
306
292
  #: (untyped, AssociationTree, String) -> Array[untyped]
307
293
  def requested_reflections(model_class, tree, path)
308
294
  tree.children.map do |name, _subtree|
309
- resolve_reflection(model_class, name, Support.association_path(path, name),
310
- root: path.empty?)
295
+ resolve_reflection(model_class, name, Support.association_path(path, name))
311
296
  end.freeze
312
297
  end
313
298
 
314
- #: (untyped, String, String, root: bool) -> untyped
315
- def resolve_reflection(model_class, name, full_path, root:)
299
+ #: (untyped, String, String) -> untyped
300
+ def resolve_reflection(model_class, name, full_path)
316
301
  reflection = model_class.reflect_on_association(name)
317
302
  raise UnknownAssociationError, "unknown association: #{full_path}" unless reflection
318
303
 
319
- reason = self.class.unsupported_reason(model_class, reflection, root: root)
304
+ reason = self.class.unsupported_reason(model_class, reflection)
320
305
  raise UnsupportedAssociationError, "unsupported association #{full_path}: #{reason}" if reason
321
306
 
322
307
  reflection
323
308
  end
324
-
325
- #: (untyped) -> bool
326
- def habtm_reflection?(reflection)
327
- reflection.macro == :has_and_belongs_to_many
328
- end
329
309
  end
330
310
  end
@@ -6,8 +6,6 @@ module PaperTrailDiff
6
6
  # of a model class. Left to the caller this is a per-root lookup, which
7
7
  # reintroduces exactly the queries a batched comparison exists to remove.
8
8
  class BatchBoundaryResolver
9
- BOUNDARIES = %i[first].freeze
10
-
11
9
  class << self
12
10
  #: (untyped) -> bool
13
11
  def symbolic?(endpoint)
@@ -45,12 +43,8 @@ module PaperTrailDiff
45
43
  #: (untyped, untyped, Hash[Array[String], untyped]) -> untyped
46
44
  def resolve(endpoint, other, firsts)
47
45
  return endpoint unless symbolic?(endpoint)
48
- raise ConfigurationError, TimelineRange::LAST_REMOVED if endpoint == :last
49
46
 
50
- unless BOUNDARIES.include?(endpoint)
51
- raise ConfigurationError,
52
- "unsupported boundary: #{endpoint.inspect}; use :first, a version, or a record"
53
- end
47
+ TimelineRange.check_symbol!(endpoint)
54
48
 
55
49
  identity = anchor_identity(other)
56
50
  unless identity
@@ -34,9 +34,8 @@ module PaperTrailDiff
34
34
 
35
35
  #: (untyped) -> bool
36
36
  def self.cut_part?(reflection)
37
- reflection.collection? &&
38
- (ScopeCondition.ranked_parts?(reflection) ||
39
- AssociationTraversal.through_parts(reflection).any?(&:has_one?))
37
+ ScopeCondition.ranked_parts?(reflection) ||
38
+ AssociationTraversal.through_parts(reflection).any?(&:has_one?)
40
39
  end
41
40
  private_class_method :cut_part?
42
41
  end