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
@@ -0,0 +1,197 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Finds the roots whose requested associations changed in a window, so that
6
+ # selecting by activity includes a record whose own row did not change.
7
+ #
8
+ # A root qualifies when a record on one of its requested paths has a version
9
+ # in the window while it belonged to that root: when the window opened, or
10
+ # after a change inside it. Those are the memberships PT-AT recorded, and the
11
+ # ones an activity analysis reads. For `has_many :through`, the join rows are
12
+ # on the path too, since creating or destroying one changes membership.
13
+ #
14
+ # Each edge is one query, walked from the leaves toward the root, never one
15
+ # per root. Ids stay in a subquery while the columns compared share a type;
16
+ # otherwise they are read and the edge runs over them in slices.
17
+ class AssociationActivitySelection
18
+ SLICE = 250
19
+ private_constant :SLICE
20
+
21
+ # The ids a one-column subquery selects, with that column's type: a
22
+ # database compares columns of one type only, and PostgreSQL rejects an
23
+ # integer key against a string item_id outright.
24
+ class Query
25
+ attr_reader :relation #: untyped
26
+ attr_reader :column #: untyped
27
+ attr_reader :type #: Symbol?
28
+
29
+ #: (untyped, untyped, Symbol?) -> void
30
+ def initialize(relation, column, type)
31
+ @relation = relation.select(column)
32
+ @column = column
33
+ @type = type
34
+ freeze
35
+ end
36
+
37
+ # A key PT-AT recorded as empty names no record, so it is left out.
38
+ #: () -> Array[untyped]
39
+ def values
40
+ @relation.distinct.pluck(@column).compact
41
+ end
42
+
43
+ # The ids with no match in `keys`, a subquery of the keys that exist.
44
+ #: (untyped) -> Array[untyped]
45
+ def missing(keys)
46
+ @relation.where(@column.not_in(keys)).distinct.pluck(@column)
47
+ end
48
+ end
49
+
50
+ # @rbs!
51
+ # type source = Query | Array[untyped]
52
+
53
+ # Every id the sources name, read from the database where needed.
54
+ #: (Array[source]) -> Array[untyped]
55
+ def self.values(sources)
56
+ sources.flat_map { |ids| ids.is_a?(Query) ? ids.values : ids }.uniq
57
+ end
58
+
59
+ #: (untyped, tree: AssociationTree, time_range: TimeRange?) -> void
60
+ def initialize(model, tree:, time_range:)
61
+ @model = model
62
+ @traversal = AssociationTraversal.new(tree)
63
+ @time_range = time_range
64
+ end
65
+
66
+ # The roots' ids, each source a subquery or an array of values.
67
+ #: () -> Array[source]
68
+ def call
69
+ reach(@model, @traversal.tree, '')
70
+ end
71
+
72
+ private
73
+
74
+ # @rbs @model: untyped
75
+ # @rbs @traversal: AssociationTraversal
76
+ # @rbs @time_range: TimeRange?
77
+
78
+ # Ids of `model` records with a change somewhere below them in `tree`: the
79
+ # targets that changed, or that reach a change further down.
80
+ #: (untyped, AssociationTree, String) -> Array[source]
81
+ def reach(model, tree, path)
82
+ @traversal.reflections_for(model, tree, path: path).flat_map do |reflection|
83
+ next polymorphic_owners(reflection) if reflection.polymorphic?
84
+
85
+ target = reflection.klass
86
+ subtree = tree.child(reflection.name) #: AssociationTree
87
+ child_path = Support.association_path(path, reflection.name)
88
+ owners(reflection, changed(target) + reach(target, subtree, child_path))
89
+ end
90
+ end
91
+
92
+ #: (untyped, Array[source]) -> Array[source]
93
+ def owners(reflection, ids)
94
+ return [] if ids.empty?
95
+ return through_owners(reflection, ids) if reflection.through_reflection?
96
+
97
+ edges(reflection).flat_map { |edge| follow(edge, ids) }
98
+ end
99
+
100
+ # A join row that changes moves membership as surely as a target that does.
101
+ #: (untyped, Array[source]) -> Array[source]
102
+ def through_owners(reflection, ids)
103
+ through = reflection.through_reflection
104
+ source_type = reflection.options[:source_type]
105
+ joins = if source_type
106
+ typed_joins(reflection, ids, source_type)
107
+ else
108
+ owners(reflection.source_reflection, ids) + changed(through.klass)
109
+ end
110
+ owners(through, joins)
111
+ end
112
+
113
+ # Under `source_type:`, only join rows of that type are members, so only
114
+ # targets of that type and changes to those rows count.
115
+ #: (untyped, Array[source], untyped) -> Array[source]
116
+ def typed_joins(reflection, ids, source_type)
117
+ edge = AssociationActivityEdge::BelongsTo.new(reflection.source_reflection, @time_range,
118
+ foreign_type: source_type)
119
+ follow(edge, ids) + changed(reflection.through_reflection.klass, edge.typed_owners)
120
+ end
121
+
122
+ # A polymorphic key's targets are known only from the types its rows name,
123
+ # and a path stops at one, so only the targets' own changes count.
124
+ #: (untyped) -> Array[source]
125
+ def polymorphic_owners(reflection)
126
+ edge = AssociationActivityEdge::BelongsTo.new(reflection, @time_range)
127
+ edge.target_types.flat_map do |name|
128
+ typed = AssociationActivityEdge::BelongsTo.new(reflection, @time_range, foreign_type: name)
129
+ follow(typed, changed(target_class(name)))
130
+ end
131
+ end
132
+
133
+ #: (untyped) -> Array[AssociationActivityEdge]
134
+ def edges(reflection)
135
+ kinds = case reflection.macro
136
+ when :belongs_to then [AssociationActivityEdge::BelongsTo]
137
+ when :has_and_belongs_to_many
138
+ [AssociationActivityEdge::LiveHabtm, AssociationActivityEdge::RecordedHabtm]
139
+ else [AssociationActivityEdge::Child]
140
+ end
141
+ kinds.map { |kind| kind.new(reflection, @time_range) }.select(&:available?)
142
+ end
143
+
144
+ # Records with a version in the window, or only those of them `item_ids`
145
+ # selects: under `source_type:`, the join rows that had that type.
146
+ #: (untyped, ?untyped) -> Array[source]
147
+ def changed(model, item_ids = nil)
148
+ return [] unless Support.versioned?(model)
149
+
150
+ versions = model.paper_trail.version_class
151
+ relation = versions.where(item_type: model.base_class.name)
152
+ relation = relation.where(item_id: item_ids) if item_ids
153
+ range = @time_range
154
+ relation = range.scope(relation) if range
155
+ [Query.new(relation, versions.arel_table[:item_id],
156
+ versions.type_for_attribute('item_id').type)]
157
+ end
158
+
159
+ # One edge for each source. A subquery whose column type matches the
160
+ # filtered column stays a subquery; anything else is read, and the edge
161
+ # runs over its values in slices.
162
+ #: (AssociationActivityEdge, Array[source]) -> Array[source]
163
+ def follow(edge, sources)
164
+ sources.filter_map do |source|
165
+ query = subquery(source, edge.filter_type)
166
+ next Query.new(edge.relation(query.relation), edge.column, edge.type) if query
167
+
168
+ found = read(edge, self.class.values([source]))
169
+ found unless found.empty?
170
+ end
171
+ end
172
+
173
+ #: (AssociationActivityEdge, Array[untyped]) -> Array[untyped]
174
+ def read(edge, values)
175
+ values.each_slice(SLICE).flat_map do |slice|
176
+ edge.relation(slice).pluck(edge.column)
177
+ end.compact.uniq
178
+ end
179
+
180
+ # Sources are only ever a Query or a plain Array, so the one mutation
181
+ # left, `instance_of?` for `is_a?`, cannot change an answer.
182
+ # mutant:disable
183
+ #: (source, Symbol?) -> Query?
184
+ def subquery(source, type)
185
+ source if source.is_a?(Query) && source.type == type
186
+ end
187
+
188
+ # A type naming no class has no versions to read; `changed` skips one that
189
+ # names an unversioned class.
190
+ #: (String) -> untyped
191
+ def target_class(name)
192
+ Object.const_get(name)
193
+ rescue NameError
194
+ nil
195
+ end
196
+ end
197
+ 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).flat_map do |reflection|
65
+ supported_reflections(model_class, root: prefix.empty?).flat_map do |reflection|
66
66
  describe_and_descend(reflection, prefix: prefix, ancestry: ancestry, depth: depth)
67
67
  end
68
68
  end
@@ -98,18 +98,21 @@ module PaperTrailDiff
98
98
  )
99
99
  end
100
100
 
101
- #: (untyped) -> Array[untyped]
102
- def supported_reflections(model_class)
103
- model_class.reflect_on_all_associations
104
- .select { |reflection| SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro) }
105
- .reject { |reflection| paper_trail_versions?(model_class, reflection) }
106
- .sort_by { |reflection| reflection.name.to_s }
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:)
104
+ reflections = model_class.reflect_on_all_associations.reject do |reflection|
105
+ AssociationTraversal.unsupported_reason(model_class, reflection, root: root) ||
106
+ unversioned?(reflection)
107
+ end
108
+ reflections.sort_by { |reflection| reflection.name.to_s }
107
109
  end
108
110
 
109
- #: (untyped, untyped) -> bool
110
- def paper_trail_versions?(model_class, reflection)
111
- model_class.respond_to?(:versions_association_name) &&
112
- reflection.name.to_s == model_class.versions_association_name.to_s
111
+ # Every request that reads history refuses a path whose target, or a
112
+ # model its has_many :through goes through, has no versions.
113
+ #: (untyped) -> bool
114
+ def unversioned?(reflection)
115
+ TraversalPreparer.unversioned_models(reflection).any?
113
116
  end
114
117
 
115
118
  #: (untyped) -> untyped
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # PT-AT records which record a child pointed at by that record's id, and
6
+ # history matches children to owners and targets by id. An association
7
+ # keyed on another column (`primary_key:`) would read other records'
8
+ # history, so it is refused.
9
+ module AssociationKey
10
+ # Why the association, or a part of a through, cannot be read by id.
11
+ #: (untyped) -> String?
12
+ def self.unsupported_reason(reflection)
13
+ part = keyed_part(reflection)
14
+ return unless part
15
+
16
+ "#{part.active_record.name}##{part.name} matches records by " \
17
+ "#{part.options[:primary_key]} rather than the primary key, and association " \
18
+ 'history is recorded by primary key'
19
+ end
20
+
21
+ # The reflection, or the first part of a through, keyed on a column other
22
+ # than its owner's or target's primary key.
23
+ #: (untyped) -> untyped
24
+ def self.keyed_part(reflection)
25
+ return reflection if other_key?(reflection)
26
+ return unless reflection.through_reflection?
27
+
28
+ [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
29
+ keyed_part(part)
30
+ end.first
31
+ end
32
+ private_class_method :keyed_part
33
+
34
+ # A belongs_to names a key of its target; any other macro, one of its
35
+ # owner. A polymorphic target has no single primary key to compare with.
36
+ #: (untyped) -> bool
37
+ def self.other_key?(reflection)
38
+ key = reflection.options[:primary_key]
39
+ return false unless key
40
+ return true if reflection.polymorphic?
41
+
42
+ model = reflection.belongs_to? ? reflection.klass : reflection.active_record
43
+ !same_column?(key, model.primary_key)
44
+ end
45
+ private_class_method :other_key?
46
+
47
+ # Column names are strings once the key is, so the one mutation left,
48
+ # `eql?` for `==`, answers the same.
49
+ # mutant:disable
50
+ #: (untyped, untyped) -> bool
51
+ def self.same_column?(key, primary_key)
52
+ key.to_s == primary_key
53
+ end
54
+ private_class_method :same_column?
55
+ end
56
+ end
@@ -3,18 +3,158 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Resolves and validates ActiveRecord reflections for a bounded association tree.
6
- class AssociationTraversal
6
+ class AssociationTraversal # rubocop:disable Metrics/ClassLength
7
7
  # The class a `belongs_to` points at for this record, reading a polymorphic
8
- # type column when there is one. Nil when that type names no class.
8
+ # type column when there is one. Nil when the record points at nothing.
9
9
  #: (untyped, untyped) -> untyped
10
10
  def self.belongs_to_target(reflection, record)
11
11
  return reflection.klass unless reflection.polymorphic?
12
12
 
13
- Object.const_get(record.public_send(reflection.foreign_type).to_s)
13
+ type = record.public_send(reflection.foreign_type).to_s
14
+ polymorphic_target(reflection, record, type) unless type.empty?
15
+ end
16
+
17
+ # A through with `source_type:` reaches only the join records whose type
18
+ # column names that class, as Active Record's `where(type => source_type)`.
19
+ # A through's `foreign_type` is its polymorphic source's.
20
+ #: (untyped, untyped) -> bool
21
+ def self.source_type_join?(reflection, join)
22
+ reflection.options[:source_type].nil? ||
23
+ source_type_member?(reflection, join.public_send(reflection.foreign_type))
24
+ end
25
+
26
+ # The same check for a join row read as stored attributes, given the
27
+ # value of its type column.
28
+ #: (untyped, untyped) -> bool
29
+ def self.source_type_member?(reflection, type)
30
+ source_type = reflection.options[:source_type]
31
+ source_type.nil? || type == source_type.to_s
32
+ end
33
+
34
+ # The class a stored type names, or nil when it names none.
35
+ # This class defines no constants of its own, so the one mutation left,
36
+ # `const_get` on it rather than on Object, finds the same class.
37
+ # mutant:disable
38
+ #: (String) -> untyped
39
+ def self.named_class(type)
40
+ Object.const_get(type)
14
41
  rescue NameError
15
42
  nil
16
43
  end
17
44
 
45
+ # A type left by a renamed or removed model names no class. Active Record
46
+ # and PT-AT raise a bare NameError for it, which does not say where it is.
47
+ #: (untyped, untyped, String) -> untyped
48
+ def self.polymorphic_target(reflection, record, type)
49
+ model_class = named_class(type)
50
+ return model_class if model_class
51
+
52
+ raise IncompleteAssociationHistoryError,
53
+ "association #{record.class.name}##{reflection.name} cannot be read: " \
54
+ "#{record.class.name} #{record.id} has #{reflection.foreign_type} #{type}, which " \
55
+ 'names no class. If the model was renamed, replace the old name in that column ' \
56
+ 'and in the versions that recorded it.'
57
+ end
58
+ private_class_method :polymorphic_target
59
+
60
+ # Why a request cannot name this association of the model, or nil when it
61
+ # can; `root` says whether the model is the record the request compares.
62
+ # Discovery lists only the associations this accepts, so every path it
63
+ # lists can be requested. A has_many :through Active Record cannot follow
64
+ # raises Active Record's own error.
65
+ #: (untyped, untyped, root: bool) -> String?
66
+ def self.unsupported_reason(model_class, reflection, root:)
67
+ return 'PaperTrail versions' if paper_trail_versions?(model_class, reflection)
68
+ return reflection.macro.to_s unless SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro)
69
+ if reflection.macro == :has_and_belongs_to_many
70
+ return habtm_reason(reflection, root) || VersionTable.unsupported_reason(reflection)
71
+ end
72
+
73
+ habtm = habtm_in_chain(reflection)
74
+ return storage_reason(reflection) unless habtm
75
+
76
+ "it goes through #{habtm.active_record.name}##{habtm.name}, a has_and_belongs_to_many, " \
77
+ 'whose hidden join model has no history to compare'
78
+ end
79
+
80
+ # History matches records by primary key, within one set of version tables.
81
+ #: (untyped) -> String?
82
+ def self.storage_reason(reflection)
83
+ AssociationKey.unsupported_reason(reflection) || VersionTable.unsupported_reason(reflection)
84
+ end
85
+ private_class_method :storage_reason
86
+
87
+ # PT-AT records a HABTM's membership only when its owner saves a version,
88
+ # in rows keyed by transaction and association name, not by owner. A root
89
+ # checkpoint so holds the root's membership and no one else's: another
90
+ # record's HABTM would read the root's rows, or none.
91
+ #: (untyped) -> String
92
+ def self.habtm_below_root(reflection)
93
+ "#{reflection.active_record.name}##{reflection.name} is a has_and_belongs_to_many " \
94
+ 'below the root, and a root checkpoint records HABTM membership for the root alone'
95
+ end
96
+ private_class_method :habtm_below_root
97
+
98
+ # PT-AT records a HABTM's membership by loading the association, scope and
99
+ # target default scope applied, so a target outside the scope when the
100
+ # owner saved is never recorded. One that enters it before the next save
101
+ # is a member then that history cannot hold.
102
+ #: (untyped, bool) -> String?
103
+ def self.habtm_reason(reflection, root)
104
+ return habtm_below_root(reflection) unless root
105
+ return unless ScopeCondition.scoped?(reflection)
106
+
107
+ "#{reflection.active_record.name}##{reflection.name} is a scoped " \
108
+ 'has_and_belongs_to_many, and PaperTrail records only the members its scope ' \
109
+ 'admitted when the owner saved, so membership between saves cannot be rebuilt; ' \
110
+ 'replace it with a has_many :through a versioned join model'
111
+ end
112
+ private_class_method :habtm_reason
113
+
114
+ #: (untyped, untyped) -> bool
115
+ def self.paper_trail_versions?(model_class, reflection)
116
+ model_class.respond_to?(:versions_association_name) &&
117
+ reflection.name.to_s == model_class.versions_association_name.to_s
118
+ end
119
+ private_class_method :paper_trail_versions?
120
+
121
+ # Active Record joins a HABTM through a hidden model of its own, which has
122
+ # no versions and no reader that PT-AT or prepared history can follow, so a
123
+ # through that crosses one would fail partway through reconstruction.
124
+ #
125
+ # The through and source reflections of a through are the hidden ones, a
126
+ # has_many in place of each HABTM, so only the public reflection of the
127
+ # same name shows the HABTM. Active Record's own check, which it runs on
128
+ # first use anyway, explains a through it cannot follow before the chain
129
+ # below it is read.
130
+ #: (untyped) -> untyped
131
+ def self.habtm_in_chain(reflection)
132
+ return unless reflection.through_reflection?
133
+
134
+ reflection.check_validity!
135
+ parts = [reflection.through_reflection, reflection.source_reflection]
136
+ parts.filter_map do |part|
137
+ link = part.active_record.reflect_on_association(part.name)
138
+ link.macro == :has_and_belongs_to_many ? link : habtm_in_chain(link)
139
+ end.first
140
+ end
141
+ private_class_method :habtm_in_chain
142
+
143
+ attr_reader :tree #: AssociationTree
144
+
145
+ # Whether a row belongs to an association whose class is `model_class`.
146
+ # Children are found by key across the whole table, so an association to an
147
+ # STI subclass has to leave out its siblings, as Active Record's type
148
+ # condition does for the live association: the row's type must name the
149
+ # class or one of its descendants. A base class takes every row.
150
+ #: (untyped, Hash[String, untyped]) -> bool
151
+ def self.sti_member?(model_class, attributes)
152
+ return true if model_class.descends_from_active_record?
153
+
154
+ names = [model_class, *model_class.descendants].map(&:sti_name)
155
+ names.include?(attributes[model_class.inheritance_column])
156
+ end
157
+
18
158
  #: (AssociationTree) -> void
19
159
  def initialize(tree)
20
160
  @tree = tree
@@ -35,7 +175,7 @@ module PaperTrailDiff
35
175
  def ensure_habtm_history!(model_class, version)
36
176
  paths = habtm_paths(model_class)
37
177
  return if paths.empty?
38
- return if version.respond_to?(:transaction_id) && version.transaction_id
178
+ return if VersionBoundary.transaction_id(version)
39
179
 
40
180
  message = "HABTM history is incomplete at version #{version.id}: #{paths.join(', ')}"
41
181
  raise IncompleteAssociationHistoryError, message
@@ -60,24 +200,23 @@ module PaperTrailDiff
60
200
  raise UnsupportedLiveActivityError, message
61
201
  end
62
202
 
203
+ # A model and a tree resolve to the same reflections wherever they are
204
+ # read: a tree is only ever walked from one place, the root tree at the
205
+ # root and a subtree below it. Beyond that, the path only names a failure,
206
+ # and a failure is not cached.
63
207
  #: (untyped, AssociationTree, path: String) -> Array[untyped]
64
208
  def reflections_for(model_class, tree, path:)
65
- key = [model_class.name.to_s, path, tree.object_id]
66
- @reflection_cache[key] ||= requested_reflections(model_class, tree, path)
209
+ @reflection_cache[[model_class, tree]] ||= requested_reflections(model_class, tree, path)
67
210
  end
68
211
 
212
+ # Active Record names keys as strings. A polymorphic child also points back
213
+ # with its type column; `type` is nil for any other.
69
214
  #: (untyped) -> Array[String]
70
215
  def incoming_relationship_columns(reflection)
71
- direct = %i[has_one has_many].include?(reflection.macro) && !reflection.options[:through]
216
+ direct = %i[has_one has_many].include?(reflection.macro) && !reflection.through_reflection?
72
217
  return [] unless direct
73
218
 
74
- foreign_keys = Array(reflection.foreign_key)
75
- # @type var foreign_keys: Array[untyped]
76
- columns = foreign_keys.map do |column| # rubocop:disable Style/SymbolProc
77
- column.to_s
78
- end
79
- columns << reflection.type.to_s if reflection.options[:as]
80
- columns
219
+ Array(reflection.foreign_key) + Array(reflection.type)
81
220
  end
82
221
 
83
222
  private
@@ -88,11 +227,12 @@ module PaperTrailDiff
88
227
  #: (untyped, AssociationTree, path: String) -> Array[Array[untyped]]
89
228
  def collect_reflections(model_class, tree, path:)
90
229
  reflections_for(model_class, tree, path: path).flat_map do |reflection|
91
- child_path = join_path(path, reflection.name.to_s)
230
+ child_path = Support.association_path(path, reflection.name)
92
231
  result = [[child_path, reflection]]
93
- subtree = tree.child(reflection.name)
94
- next result unless subtree && !subtree.empty? && !reflection.polymorphic?
232
+ next result if reflection.polymorphic?
95
233
 
234
+ # A leaf's subtree is empty and adds nothing.
235
+ subtree = tree.child(reflection.name) #: AssociationTree
96
236
  result + collect_reflections(reflection.klass, subtree, path: child_path)
97
237
  end
98
238
  end
@@ -100,55 +240,48 @@ module PaperTrailDiff
100
240
  #: (untyped, AssociationTree, path: String) -> void
101
241
  def validate_tree!(model_class, tree, path:)
102
242
  reflections_for(model_class, tree, path: path).each do |reflection|
103
- subtree = tree.child(reflection.name)
104
- next unless subtree && !subtree.empty? && !reflection.polymorphic?
243
+ subtree = tree.child(reflection.name) #: AssociationTree
244
+ next if subtree.empty?
105
245
 
106
- child_path = join_path(path, reflection.name.to_s)
246
+ child_path = Support.association_path(path, reflection.name)
247
+ reject_polymorphic_descent!(reflection, subtree, child_path)
107
248
  validate_tree!(reflection.klass, subtree, path: child_path)
108
249
  end
109
250
  end
110
251
 
252
+ # A polymorphic target's class differs from record to record, so the
253
+ # associations a path names below it may not exist on every target.
254
+ #: (untyped, AssociationTree, String) -> void
255
+ def reject_polymorphic_descent!(reflection, subtree, path)
256
+ return unless reflection.polymorphic?
257
+
258
+ raise UnsupportedAssociationError,
259
+ "unsupported association #{subtree.paths(prefix: path).first}: " \
260
+ "#{path} is polymorphic, so a path cannot continue past it"
261
+ end
262
+
111
263
  #: (untyped, AssociationTree, String) -> Array[untyped]
112
264
  def requested_reflections(model_class, tree, path)
113
265
  tree.children.map do |name, _subtree|
114
- resolve_reflection(model_class, name, join_path(path, name))
266
+ resolve_reflection(model_class, name, Support.association_path(path, name),
267
+ root: path.empty?)
115
268
  end.freeze
116
269
  end
117
270
 
118
- #: (untyped, String, String) -> untyped
119
- def resolve_reflection(model_class, name, full_path)
120
- reflection = model_class.reflect_on_association(name.to_sym)
271
+ #: (untyped, String, String, root: bool) -> untyped
272
+ def resolve_reflection(model_class, name, full_path, root:)
273
+ reflection = model_class.reflect_on_association(name)
121
274
  raise UnknownAssociationError, "unknown association: #{full_path}" unless reflection
122
275
 
123
- if paper_trail_versions?(model_class, reflection)
124
- message = "unsupported association #{full_path}: PaperTrail versions"
125
- raise UnsupportedAssociationError, message
126
- end
127
- unless SUPPORTED_ASSOCIATION_MACROS.include?(reflection.macro)
128
- raise UnsupportedAssociationError,
129
- "unsupported association #{full_path}: #{reflection.macro}"
130
- end
276
+ reason = self.class.unsupported_reason(model_class, reflection, root: root)
277
+ raise UnsupportedAssociationError, "unsupported association #{full_path}: #{reason}" if reason
131
278
 
132
279
  reflection
133
280
  end
134
281
 
135
- #: (untyped, untyped) -> bool
136
- def paper_trail_versions?(model_class, reflection)
137
- model_class.respond_to?(:versions_association_name) &&
138
- reflection.name.to_s == model_class.versions_association_name.to_s
139
- end
140
-
141
282
  #: (untyped) -> bool
142
283
  def habtm_reflection?(reflection)
143
- return true if reflection.macro == :has_and_belongs_to_many
144
- return false unless reflection.options[:through]
145
-
146
- habtm_reflection?(reflection.through_reflection)
147
- end
148
-
149
- #: (String, String) -> String
150
- def join_path(parent, name)
151
- parent.empty? ? name : "#{parent}.#{name}"
284
+ reflection.macro == :has_and_belongs_to_many
152
285
  end
153
286
  end
154
287
  end
@@ -113,10 +113,9 @@ module PaperTrailDiff
113
113
  # a tie -- refusing one that ids cannot order.
114
114
  #: (untyped, Array[untyped]) -> Hash[String, untyped]
115
115
  def first_versions(model_class, ids)
116
- version_class = model_class.paper_trail.version_class
117
- table = version_class.arel_table
118
- candidates = version_class.where(item_type: model_class.base_class.name.to_s, item_id: ids)
119
- .where(VersionQuery.no_earlier_version(table)).to_a
116
+ table = model_class.paper_trail.version_class.arel_table
117
+ candidates = VersionQuery.for_items(model_class, ids)
118
+ .where(VersionQuery.no_earlier_version(table)).to_a
120
119
  candidates.group_by { |version| version.item_id.to_s }
121
120
  .transform_values { |versions| Support.chronological_sort(versions).first }
122
121
  end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Which associations Active Record's preloader loads correctly for many
6
+ # owners at once.
7
+ module BatchPreload
8
+ # The preloader applies a limit or offset to all owners' records at once,
9
+ # not to each owner's, so such an association is loaded per record. A
10
+ # has_one is no exception. Through a part with a limit, an offset or a
11
+ # has_one cut, the preloader keeps what the part alone would load, while
12
+ # the through's own query keeps the part's conditions only.
13
+ #
14
+ # The declared scope is read, not a record's association scope: Active
15
+ # Record adds `limit(1)` to every has_one's, which would load every
16
+ # has_one per record.
17
+ #: (untyped) -> bool
18
+ def self.safe?(reflection)
19
+ scope = reflection.scope
20
+ return false if scope && !scope.arity.zero?
21
+ return true unless reflection.collection? || reflection.has_one?
22
+ return false if cut_part?(reflection)
23
+
24
+ relation = declared_relation(reflection)
25
+ relation.limit_value.nil? && relation.offset_value.nil?
26
+ end
27
+
28
+ #: (untyped) -> untyped
29
+ def self.declared_relation(reflection)
30
+ relation = reflection.klass.default_scoped
31
+ reflection.scope ? reflection.scope_for(relation) : relation
32
+ end
33
+ private_class_method :declared_relation
34
+
35
+ #: (untyped) -> bool
36
+ def self.cut_part?(reflection)
37
+ reflection.collection? &&
38
+ (ScopeCondition.ranked_parts?(reflection) || through_parts(reflection).any?(&:has_one?))
39
+ end
40
+ private_class_method :cut_part?
41
+
42
+ # Every part a through passes, at any depth.
43
+ #: (untyped) -> Array[untyped]
44
+ def self.through_parts(reflection)
45
+ return [] unless reflection.through_reflection?
46
+
47
+ [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
48
+ [part, *through_parts(part)]
49
+ end
50
+ end
51
+ private_class_method :through_parts
52
+ end
53
+ end