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
@@ -14,9 +14,8 @@ module PaperTrailDiff
14
14
 
15
15
  # Unranked, as a part of a has_many through is read, it returns every row
16
16
  # the part's conditions admit, a record reached twice appearing twice.
17
- #: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [bool, Array[PreparedRecordState]]
17
+ #: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> Array[PreparedRecordState]
18
18
  def call(owner, reflection, boundary, ranked: true)
19
- return [false, []] unless supported?(reflection, ranked)
20
19
  return through(owner, reflection, boundary, ranked) if reflection.options[:through]
21
20
  return target(owner, reflection, boundary, ranked) if reflection.belongs_to?
22
21
 
@@ -29,58 +28,85 @@ module PaperTrailDiff
29
28
  # @rbs @edges: untyped
30
29
  # @rbs @conditions: ScopeCondition::Cache
31
30
 
32
- # A polymorphic target's class is known only once a record names it, so
33
- # `target` reads its scope for each record instead.
34
- #: (untyped, bool) -> bool
35
- def supported?(reflection, ranked)
36
- !reflection.foreign_key.is_a?(Array) &&
37
- %i[belongs_to has_one has_many].include?(reflection.macro) &&
38
- (reflection.polymorphic? || !@conditions.call(reflection, ranked: ranked).nil?)
39
- end
40
-
41
31
  #: (PreparedRecordState, untyped, bool, ?untyped) -> bool
42
32
  def in_scope?(state, reflection, ranked, model_class = reflection.klass)
43
33
  condition = @conditions.call(reflection, model_class, ranked: ranked) #: ScopeCondition
44
34
  condition.matches?(state.attributes)
45
35
  end
46
36
 
47
- # A type that names no class, or a class whose scope cannot be read as
48
- # conditions, is left to the record path, which raises for the first and
49
- # reads the second through its association.
50
- #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
37
+ #: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
51
38
  def target(owner, reflection, boundary, ranked)
52
39
  id = owner.attributes[reflection.foreign_key.to_s]
53
- return [true, []] if id.nil?
40
+ return [] if id.nil? || untyped?(owner, reflection)
41
+
42
+ model_class = target_class(owner, reflection, id, ranked)
43
+ state = @records.snapshot_state_before(model_class, id, boundary)
44
+ state && target?(state, reflection, ranked, model_class) ? [state] : []
45
+ end
46
+
47
+ # A polymorphic key with no type names no target, as Active Record reads it.
48
+ #: (PreparedRecordState, untyped) -> bool
49
+ def untyped?(owner, reflection)
50
+ reflection.polymorphic? && owner.attributes[reflection.foreign_type].to_s.empty?
51
+ end
54
52
 
53
+ #: (PreparedRecordState, untyped, untyped, bool) -> untyped
54
+ def target_class(owner, reflection, id, ranked)
55
55
  type = owner.attributes[reflection.foreign_type]
56
56
  model_class = AssociationTraversal.stored_target(reflection, type)
57
- return [false, []] unless model_class &&
58
- @conditions.call(reflection, model_class, ranked: ranked)
57
+ readable = model_class && @conditions.call(reflection, model_class, ranked: ranked) &&
58
+ @records.loaded?(model_class, id)
59
+ return model_class if readable
59
60
 
60
- handled, state = @records.snapshot_state_before(model_class, id, boundary)
61
- [handled, state && in_scope?(state, reflection, ranked, model_class) ? [state] : []]
61
+ unreadable!(owner, reflection, type, model_class)
62
62
  end
63
63
 
64
- # The members of each join record the owner had at the boundary, as
65
- # PreparedHistory#through_records reads them from records. Under
66
- # `source_type:`, only join records of that type count. A has_many
67
- # through reads its parts unranked, as its query does.
68
- #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
69
- def through(owner, reflection, boundary, ranked)
70
- parts_ranked = ranked && !reflection.collection?
71
- handled, joins = call(owner, reflection.through_reflection, boundary, ranked: parts_ranked)
72
- return [false, []] unless handled
64
+ # A polymorphic target's class is known only from the owner's type
65
+ # column, so TraversalPreparer cannot check it up front: the type may name
66
+ # no class, or one with no versions or a default scope history cannot read.
67
+ #: (PreparedRecordState, untyped, untyped, untyped) -> bot
68
+ def unreadable!(owner, reflection, type, model_class)
69
+ owner_class = owner.model_class
70
+ id = owner_id(owner)
71
+ if model_class.nil? && !type.to_s.empty?
72
+ AssociationTraversal.unnamed_target!(reflection, owner_class, id, type)
73
+ end
74
+ name = "#{owner_class.name}##{reflection.name}"
75
+ unversioned!(name, model_class) unless model_class.nil? || Support.versioned?(model_class)
73
76
 
74
- rows = [] #: Array[PreparedRecordState]
75
- joins.each do |join|
76
- next unless typed_join?(reflection, join)
77
+ raise UnsupportedAssociationError,
78
+ "association #{name} cannot be read from history for #{owner_class.name} " \
79
+ "#{id}: who was in it at a past point cannot be told"
80
+ end
77
81
 
78
- handled, states = call(join, reflection.source_reflection, boundary, ranked: parts_ranked)
79
- return [false, []] unless handled
82
+ #: (String, untyped) -> bot
83
+ def unversioned!(name, model_class)
84
+ raise UnversionedAssociationError,
85
+ "association #{name} cannot be compared historically: it points at " \
86
+ "#{model_class.name}, which is not versioned. Add `has_paper_trail` to " \
87
+ "#{model_class.name}, or mirror the fields you need onto a model that has it."
88
+ end
80
89
 
81
- rows.concat(states)
90
+ # A target class that is an STI subclass reads no sibling's row, as Active
91
+ # Record's type condition reads none.
92
+ #: (PreparedRecordState, untyped, bool, untyped) -> bool
93
+ def target?(state, reflection, ranked, model_class)
94
+ AssociationTraversal.sti_member?(model_class, state.attributes) &&
95
+ in_scope?(state, reflection, ranked, model_class)
96
+ end
97
+
98
+ # The members of each join record the owner had at the boundary. Under
99
+ # `source_type:`, only join records of that type count. A through reads
100
+ # its parts unranked, as its one query joins every row of each.
101
+ #: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
102
+ def through(owner, reflection, boundary, ranked)
103
+ joins = call(owner, reflection.through_reflection, boundary, ranked: false)
104
+ rows = ScopeCondition.in_key_order(joins, &:model_class).flat_map do |join|
105
+ next [] unless typed_join?(reflection, join)
106
+
107
+ call(join, reflection.source_reflection, boundary, ranked: false)
82
108
  end
83
- [true, through_members(reflection, rows, ranked)]
109
+ through_members(reflection, rows, ranked)
84
110
  end
85
111
 
86
112
  # The through's own scope applies after its parts' scopes, to each row,
@@ -91,13 +117,15 @@ module PaperTrailDiff
91
117
  members = condition.members(rows)
92
118
  return members unless ranked
93
119
 
94
- first_if_one(reflection, members.uniq { |state| identity(state) })
120
+ first_if_one(reflection, condition, members.uniq { |state| identity(state) })
95
121
  end
96
122
 
97
- # A has_one keeps the first of its records.
98
- #: (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
99
- def first_if_one(reflection, states)
100
- reflection.collection? ? states : states.first(1)
123
+ # A has_one keeps one of its records (see ScopeCondition#first).
124
+ #: (untyped, ScopeCondition, Array[PreparedRecordState]) -> Array[PreparedRecordState]
125
+ def first_if_one(reflection, condition, states)
126
+ return states if reflection.collection?
127
+
128
+ condition.first(states, in_order: AssociationTraversal.join_order?(reflection))
101
129
  end
102
130
 
103
131
  #: (untyped, PreparedRecordState) -> bool
@@ -114,22 +142,20 @@ module PaperTrailDiff
114
142
 
115
143
  # The scope's condition and the owner's id are read once for all the
116
144
  # owner's children, which are read at every boundary.
117
- #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
145
+ #: (PreparedRecordState, untyped, untyped, bool) -> Array[PreparedRecordState]
118
146
  def children(owner, reflection, boundary, ranked)
119
147
  condition = @conditions.call(reflection, ranked: ranked) #: ScopeCondition
120
148
  owner_id = owner_id(owner)
121
149
  selected = [] #: Array[PreparedRecordState]
122
150
  @edges.call(owner.model_class, reflection).each_value do |group|
123
151
  ids_for(group, owner_id).each do |id|
124
- handled, child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
125
- return [false, []] unless handled
126
-
127
- selected << child if child && member?(child, owner, owner_id, reflection, condition)
152
+ child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
153
+ selected << child if child && member?(child, owner_id, reflection, condition)
128
154
  end
129
155
  end
130
- return [true, selected] unless ranked
156
+ return selected unless ranked
131
157
 
132
- [true, first_if_one(reflection, condition.rank(selected))]
158
+ first_if_one(reflection, condition, condition.rank(selected))
133
159
  end
134
160
 
135
161
  #: (untyped, String) -> Array[untyped]
@@ -139,27 +165,24 @@ module PaperTrailDiff
139
165
  owners ? owners.fetch(owner_id, empty) : group.fetch(:ids)
140
166
  end
141
167
 
142
- #: (PreparedRecordState, PreparedRecordState, String, untyped, ScopeCondition) -> bool
143
- def member?(child, owner, owner_id, reflection, condition)
168
+ #: (PreparedRecordState, String, untyped, ScopeCondition) -> bool
169
+ def member?(child, owner_id, reflection, condition)
144
170
  attributes = child.attributes
145
- return false unless attributes[reflection.foreign_key.to_s].to_s == owner_id
146
- return false unless AssociationTraversal.sti_member?(reflection.klass, attributes)
147
- return false unless condition.matches?(attributes)
148
- return true unless reflection.options[:as]
171
+ attributes[reflection.foreign_key.to_s].to_s == owner_id &&
172
+ AssociationTraversal.sti_member?(reflection.klass, attributes) &&
173
+ condition.matches?(attributes) && owner_typed?(attributes, reflection)
174
+ end
149
175
 
150
- matching_type?(child, owner.model_class, reflection)
176
+ # An `as:` child names its owner by type as well.
177
+ #: (Hash[String, untyped], untyped) -> bool
178
+ def owner_typed?(attributes, reflection)
179
+ !reflection.options[:as] ||
180
+ AssociationTraversal.owner_type(reflection) == attributes[reflection.type.to_s].to_s
151
181
  end
152
182
 
153
183
  #: (PreparedRecordState) -> String
154
184
  def owner_id(owner)
155
185
  owner.attributes[owner.model_class.primary_key].to_s
156
186
  end
157
-
158
- #: (PreparedRecordState, untyped, untyped) -> bool
159
- def matching_type?(child, model, reflection)
160
- types = [model.name, model.base_class.name,
161
- reflection.active_record.name]
162
- types.include?(child.attributes[reflection.type.to_s].to_s)
163
- end
164
187
  end
165
188
  end
@@ -11,7 +11,9 @@ module PaperTrailDiff
11
11
  #
12
12
  # PaperTrail's `version.changeset` finds the model through `version.item`,
13
13
  # which is a query per version and nothing at all once the record is deleted.
14
- # The version already names its model, so neither is needed here.
14
+ # The version already names its model, and an STI subclass's types are
15
+ # read from the class it recorded (see RecordedClass), so neither is needed
16
+ # here.
15
17
  class RecordedChanges
16
18
  IGNORE_NAMES_REQUIRED = 'ignore: must be an array of strings or symbols; a version ' \
17
19
  'has no association path for paths: to match'
@@ -33,9 +35,10 @@ module PaperTrailDiff
33
35
  raise InvalidEndpointError, 'expected a PaperTrail version' unless Endpoint.version?(@version)
34
36
 
35
37
  ignored = ignored_names
38
+ ReadableHistory.check_version!(@version, 'object_changes')
36
39
  return unless recorded?
37
40
 
38
- model_class = Endpoint.model_class(@version)
41
+ model_class = RecordedClass.for(@version)
39
42
  changes = ActivityEventRecordResolver.new.deserialized_changeset(@version, model_class)
40
43
  return if changes.nil?
41
44
 
@@ -61,22 +64,43 @@ module PaperTrailDiff
61
64
  end
62
65
 
63
66
  # Without the column, or with it left empty for this version, nothing was
64
- # recorded. That is not the same answer as a recorded empty changeset.
67
+ # recorded. That is not the same answer as a recorded empty changeset. A
68
+ # version need not be an Active Record model, as for compare.
65
69
  #: () -> bool
66
70
  def recorded?
67
- @version.class.column_names.include?('object_changes') && !@version.object_changes.nil?
71
+ @version.respond_to?(:object_changes) && !@version.object_changes.nil?
72
+ end
73
+
74
+ # An adapter may name its changes with symbols.
75
+ #: (untyped) -> Hash[String, untyped]
76
+ def named(changes)
77
+ changes.to_h { |name, values| [name.to_s, values] }
68
78
  end
69
79
 
70
80
  # Primary keys identify the record rather than describe it, as in a diff.
71
81
  # Each side is read as a step's diff reads it (see StoredValues), so a
72
- # value compares equal to the state the change produced.
82
+ # value compares equal to the state the change produced. A name the model
83
+ # no longer has, such as a column since dropped, is left out, as a diff
84
+ # leaves it out. So is a change whose sides read alike, as a diff compares
85
+ # them: Rails records a value assigned in another form than the column
86
+ # keeps, such as a time of day with another date, though the row holds
87
+ # what it held.
88
+ # Each side of the changes in the form the database stores it.
89
+ #: (untyped, Hash[String, untyped]) -> [Hash[String, untyped], Hash[String, untyped]]
90
+ def stored_sides(model_class, kept)
91
+ [StoredValues.apply(model_class, kept.transform_values(&:first)),
92
+ StoredValues.apply(model_class, kept.transform_values(&:last))]
93
+ end
94
+
73
95
  #: (untyped, untyped, Array[String]) -> Hash[String, ValueChange]
74
96
  def value_changes(model_class, changes, excluded)
75
- kept = changes.to_h { |name, values| [name.to_s, values] }.except(*excluded)
76
- from = StoredValues.apply(model_class, kept.transform_values(&:first))
77
- to = StoredValues.apply(model_class, kept.transform_values(&:last))
78
- kept.keys.sort.to_h { |key| [key, ValueChange.new(from: from.fetch(key), to: to.fetch(key))] }
79
- .freeze
97
+ kept = named(changes).slice(*model_class.column_names).except(*excluded)
98
+ from, to = stored_sides(model_class, kept)
99
+ kept.keys.sort.filter_map do |key|
100
+ before = from.fetch(key)
101
+ after = to.fetch(key)
102
+ [key, ValueChange.new(from: before, to: after)] unless Support.same?(before, after)
103
+ end.to_h.freeze
80
104
  end
81
105
  end
82
106
  end
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # PT-AT records a child's owner on the child's own versions, once for each
6
+ # belongs_to the child declares: the owner's id under the foreign key's
7
+ # name, with the class that belongs_to names. A has_many or has_one is read
8
+ # back from those rows.
9
+ module RecordedOwner
10
+ # The names a row may hold for an owner of this class. A polymorphic key
11
+ # names the owner's base class. A plain belongs_to names the class it was
12
+ # declared with, which under single-table inheritance may be any class of
13
+ # the owner's table and not the owner's own. A row with no type is
14
+ # anyone's.
15
+ #: (untyped, untyped) -> Array[String?]
16
+ def self.types(reflection, owner_class)
17
+ [nil, '', owner_class.name, owner_class.base_class.name, *declared_types(reflection)].uniq
18
+ end
19
+
20
+ # Why history cannot say which records left a has_many or has_one, or a
21
+ # part of a through: its target declares no belongs_to on the foreign
22
+ # key, so no version of a target names an owner. Such a path would show
23
+ # the records it holds now, and none that was destroyed or moved away.
24
+ #: (untyped) -> String?
25
+ def self.unsupported_reason(reflection)
26
+ part = [reflection, *AssociationTraversal.through_parts(reflection)].find do |candidate|
27
+ unrecorded?(candidate)
28
+ end
29
+ return unless part
30
+
31
+ owner = part.active_record.name
32
+ "#{part.klass.name} declares no belongs_to on #{part.foreign_key}, so its versions do not " \
33
+ "record the #{owner} that held it, and one that left #{owner}##{part.name} cannot be found"
34
+ end
35
+
36
+ # A belongs_to is recorded on the owner's own versions, and
37
+ # a through by its parts. A target without versions is refused for that.
38
+ #: (untyped) -> bool
39
+ def self.unrecorded?(part)
40
+ return false unless %i[has_many has_one].include?(part.macro)
41
+ return false if part.through_reflection?
42
+
43
+ Support.versioned?(part.klass) && inverses(part.klass, part).empty?
44
+ end
45
+ private_class_method :unrecorded?
46
+
47
+ # The classes named by the belongs_to associations on the reflection's
48
+ # foreign key, as its target declares them or a subclass of its target
49
+ # does.
50
+ #: (untyped) -> Array[String]
51
+ def self.declared_types(reflection)
52
+ [reflection.klass, *reflection.klass.descendants]
53
+ .flat_map { |model| inverses(model, reflection) }
54
+ .reject(&:polymorphic?).map { |inverse| inverse.klass.name }
55
+ end
56
+ private_class_method :declared_types
57
+
58
+ # The model's belongs_to associations on the reflection's foreign key.
59
+ #: (untyped, untyped) -> Array[untyped]
60
+ def self.inverses(model, reflection)
61
+ model.reflect_on_all_associations(:belongs_to).select do |inverse|
62
+ inverse.foreign_key == reflection.foreign_key
63
+ end
64
+ end
65
+ private_class_method :inverses
66
+ end
67
+ end
@@ -81,14 +81,18 @@ module PaperTrailDiff
81
81
  # An activity view still needs a root to reconstruct from even when no root
82
82
  # version falls inside the window, because descendants may have moved. With
83
83
  # no later version, a window closing on current state reads the root from
84
- # the live record, which is then its state throughout the window.
84
+ # the live record, which is then its state throughout the window. With
85
+ # neither, the root was gone before the window began, and it reports
86
+ # nothing. Over a whole history, a root with no versions at all has none
87
+ # to report either, as when it is read alone (see TimelineRange#unresolved?).
85
88
  #: () -> RootVersionPlan
86
89
  def without_selection
87
90
  return RootVersionPlan.empty unless @context_required
91
+ return RootVersionPlan.empty if @in_range.empty? && !@windowed
88
92
  if @after_range
89
93
  return RootVersionPlan.contiguous([@after_range], context_version: @after_range)
90
94
  end
91
- return RootVersionPlan.closing_on(@live_endpoint) if @live_endpoint && @windowed
95
+ return RootVersionPlan.closing_on(@live_endpoint) if @windowed
92
96
 
93
97
  raise IncompleteTimeRangeError, INCOMPLETE
94
98
  end