paper_trail_diff 0.17.0 → 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 +663 -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 +35 -28
  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 +235 -179
  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 +28 -4
  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 +21 -19
  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 +149 -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 +16 -2
  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
@@ -6,9 +6,35 @@ module PaperTrailDiff
6
6
  # caller, because the one that reveals the last selected mutation is drawn
7
7
  # from them.
8
8
  class VersionScopeFilter
9
- # A filter is a callable that narrows the version relation.
9
+ # The filter, checked once where it is given: a callable that takes the
10
+ # version relation, and that wherever it is called returns it narrowed,
11
+ # or an array of its versions. A relation on another table would be read
12
+ # for its ids all the same, and choose the versions that happen to share
13
+ # them.
10
14
  # : (untyped) -> untyped
11
- def self.validated: (untyped) -> untyped
15
+ def self.checked: (untyped) -> untyped
16
+
17
+ # A proc that is not a lambda takes any number of arguments.
18
+ # : (untyped) -> bool
19
+ def self.takes_relation?: (untyped) -> bool
20
+
21
+ # : (untyped, untyped) -> untyped
22
+ def self.narrowed: (untyped, untyped) -> untyped
23
+
24
+ # The versions of `relation` that activity on associations reports under
25
+ # the filter (see ActivityScopeFilter): those it keeps, and those of a
26
+ # transaction it keeps a version of, of any record in their table. A
27
+ # table without transactions keeps each version alone.
28
+ # : (untyped, untyped) -> untyped
29
+ def self.whole_transactions: (untyped, untyped) -> untyped
30
+
31
+ # A column of what the filter returned, read in the database where it
32
+ # returned a relation.
33
+ # : (untyped, Symbol) -> untyped
34
+ def self.values: (untyped, Symbol) -> untyped
35
+
36
+ # : (untyped) -> bool
37
+ def self.versions?: (untyped) -> bool
12
38
 
13
39
  # : (untyped) -> void
14
40
  def initialize: (untyped) -> void
@@ -2,11 +2,11 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Checks the recorded sequence itself, before any question of association
5
- # setup: whether the versions can be ordered at all, and whether timestamps
6
- # they share hide changes from a path PT-AT reads.
5
+ # setup: whether the versions can be ordered at all, and whether they are
6
+ # dated in the order they were saved.
7
7
  class VersionSequenceDiagnostics
8
- # : (untyped, untyped, ?fallback_selected: bool) -> void
9
- def initialize: (untyped, untyped, ?fallback_selected: bool) -> void
8
+ # : (untyped, untyped) -> void
9
+ def initialize: (untyped, untyped) -> void
10
10
 
11
11
  # The read runs in a savepoint, so that a query that fails here leaves a
12
12
  # snapshot transaction around it usable: PostgreSQL refuses every later
@@ -16,8 +16,6 @@ module PaperTrailDiff
16
16
 
17
17
  private
18
18
 
19
- @fallback_selected: bool
20
-
21
19
  @from_version: untyped
22
20
 
23
21
  @to_version: untyped
@@ -41,15 +39,6 @@ module PaperTrailDiff
41
39
  # : (untyped, untyped) -> String
42
40
  def inverted_message: (untyped, untyped) -> String
43
41
 
44
- # Loaded history orders versions that share a timestamp by id, but PT-AT
45
- # places association changes by timestamp alone, so a path it reads loses
46
- # any change between such a pair. Unlike an unorderable sequence this is
47
- # not always wrong: if nothing that path reaches changed between them the
48
- # result is correct, and the gem cannot tell which it is, because not
49
- # seeing the change is the symptom. So it warns.
50
- # : (Array[untyped]) -> DiagnosticIssue?
51
- def tied_timestamps: (Array[untyped]) -> DiagnosticIssue?
52
-
53
42
  # : () -> Array[untyped]
54
43
  def ordered_range_versions: () -> Array[untyped]
55
44
 
@@ -27,6 +27,10 @@ module PaperTrailDiff
27
27
  # : (untyped, untyped) -> untyped
28
28
  def self.joined: (untyped, untyped) -> untyped
29
29
 
30
+ # Without PT-AT loaded there are no version associations to name, and
31
+ # TraversalPreparer refuses history for that reason first, so only the
32
+ # versions' table is compared: a live comparison or association_paths
33
+ # still works.
30
34
  # : (untyped) -> String
31
35
  def self.tables: (untyped) -> String
32
36
  end
@@ -9,33 +9,24 @@ module PaperTrailDiff
9
9
  SUPPORTED_ASSOCIATION_MACROS: untyped
10
10
 
11
11
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
12
- # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
13
- def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
12
+ # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option) -> Diff
13
+ def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option) -> Diff
14
14
 
15
15
  # Compares many independent endpoint pairs while batching current-record loading.
16
- # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
17
- def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
18
-
19
- # Compares every adjacent reconstructed state in an inclusive version range,
20
- # by default the record's whole history through its current state.
21
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
22
- def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
23
-
24
- # Compares adjacent root and selected-descendant activity boundaries.
25
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
26
- def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
16
+ # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option) -> comparison_results
17
+ def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option) -> comparison_results
27
18
 
28
19
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
29
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
30
- def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
20
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool?) -> Analysis
21
+ def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool?) -> Analysis
31
22
 
32
23
  # Analyzes an array of records over one shared range, preparing their
33
24
  # selected history once for the batch instead of once per record, and
34
25
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
35
26
  # the window return an empty `Analysis`. To let a relation choose the
36
27
  # records, use `analyze_scope`.
37
- # : (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
38
- def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
28
+ # : (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool?) -> Hash[identity, Analysis]
29
+ def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool?) -> Hash[identity, Analysis]
39
30
 
40
31
  # Analyzes every root the relation reaches whose history moved inside the
41
32
  # window. With `activity: true`, a change to a record on one of the
@@ -63,15 +54,17 @@ module PaperTrailDiff
63
54
  # Note also that a relation selects on current state, not on state during
64
55
  # the window: `where(status: 'published')` means published *now*, which is a
65
56
  # different set from what was published while the window was open.
66
- # : (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
67
- def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
57
+ # : (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?recorded_changes: bool?) -> ScopedAnalysis
58
+ def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?recorded_changes: bool?) -> ScopedAnalysis
68
59
 
69
60
  # Recent root and selected-child activity through the current saved state,
70
61
  # for every root that changed or whose requested associations did.
71
62
  # Historical windows remain explicit on analyze_scope; this entry point is
72
63
  # deliberately named for a report through now rather than an as-of query.
73
- # : (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
74
- def self.report: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
64
+ # With associations, each saved transaction is one step unless `group:
65
+ # nil` asks for every version on its own.
66
+ # : (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?recorded_changes: bool?) -> ScopedAnalysis
67
+ def self.report: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?recorded_changes: bool?) -> ScopedAnalysis
75
68
 
76
69
  # Warns about deprecated options; see Deprecation.
77
70
  # : () -> untyped
@@ -88,8 +81,8 @@ module PaperTrailDiff
88
81
  # Reports known reconstruction hazards without mutating application state,
89
82
  # for the endpoints `compare` takes: two versions, or a version and the
90
83
  # current record. Every reason `compare` would refuse them is an error.
91
- # : (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
92
- def self.diagnose: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
84
+ # : (untyped, untyped, ?associations: association_option) -> DiagnosticReport
85
+ def self.diagnose: (untyped, untyped, ?associations: association_option) -> DiagnosticReport
93
86
 
94
87
  # Looks inside an attribute the database stores whole, such as a JSON or
95
88
  # jsonb column, and reports which keys changed.
@@ -125,6 +118,12 @@ module PaperTrailDiff
125
118
  # takes attribute names, as an array, and defaults to `updated_at`.
126
119
  # : (untyped, ?ignore: Array[String | Symbol]) -> Hash[String, ValueChange]?
127
120
  def self.recorded_changes: (untyped, ?ignore: Array[String | Symbol]) -> Hash[String, ValueChange]?
121
+
122
+ # `report` groups by transaction unless it reads no associations. A value
123
+ # that is not a list, such as nil, groups too, and the option's own check
124
+ # then refuses it, naming the option.
125
+ # : (untyped) -> Symbol?
126
+ private def self.default_group: (untyped) -> Symbol?
128
127
  end
129
128
 
130
129
  module PaperTrailDiff
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: paper_trail_diff
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.17.0
4
+ version: 0.18.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Alex Williams
@@ -87,15 +87,15 @@ files:
87
87
  - lib/paper_trail_diff/activity_scope_filter.rb
88
88
  - lib/paper_trail_diff/activity_snapshot_delta.rb
89
89
  - lib/paper_trail_diff/activity_snapshot_sequence.rb
90
- - lib/paper_trail_diff/activity_target_candidate_loader.rb
91
90
  - lib/paper_trail_diff/activity_timeline_builder.rb
91
+ - lib/paper_trail_diff/activity_transaction_applier.rb
92
92
  - lib/paper_trail_diff/activity_transaction_grouper.rb
93
93
  - lib/paper_trail_diff/activity_tree_filter.rb
94
+ - lib/paper_trail_diff/activity_tree_places.rb
94
95
  - lib/paper_trail_diff/activity_version_collector.rb
95
96
  - lib/paper_trail_diff/activity_view.rb
96
97
  - lib/paper_trail_diff/analysis.rb
97
98
  - lib/paper_trail_diff/analysis_batch.rb
98
- - lib/paper_trail_diff/approximate_paths.rb
99
99
  - lib/paper_trail_diff/association_activity_edge.rb
100
100
  - lib/paper_trail_diff/association_activity_selection.rb
101
101
  - lib/paper_trail_diff/association_diff_traversal.rb
@@ -108,6 +108,7 @@ files:
108
108
  - lib/paper_trail_diff/batched_root_analyzer.rb
109
109
  - lib/paper_trail_diff/batched_root_versions.rb
110
110
  - lib/paper_trail_diff/branch_snapshot_refresher.rb
111
+ - lib/paper_trail_diff/candidate_table.rb
111
112
  - lib/paper_trail_diff/change_attribution.rb
112
113
  - lib/paper_trail_diff/change_row.rb
113
114
  - lib/paper_trail_diff/collection_comparator.rb
@@ -115,6 +116,7 @@ files:
115
116
  - lib/paper_trail_diff/collection_transition.rb
116
117
  - lib/paper_trail_diff/comparison_batch.rb
117
118
  - lib/paper_trail_diff/configuration.rb
119
+ - lib/paper_trail_diff/database_time.rb
118
120
  - lib/paper_trail_diff/deleted_analysis_batch.rb
119
121
  - lib/paper_trail_diff/deleted_root_filter.rb
120
122
  - lib/paper_trail_diff/deprecation.rb
@@ -123,10 +125,7 @@ files:
123
125
  - lib/paper_trail_diff/endpoint.rb
124
126
  - lib/paper_trail_diff/engine.rb
125
127
  - lib/paper_trail_diff/errors.rb
126
- - lib/paper_trail_diff/fallback_paths.rb
127
- - lib/paper_trail_diff/habtm_transaction_owners.rb
128
- - lib/paper_trail_diff/historical_association_reifier.rb
129
- - lib/paper_trail_diff/historical_filter.rb
128
+ - lib/paper_trail_diff/exact_column_type.rb
130
129
  - lib/paper_trail_diff/historical_snapshot_store.rb
131
130
  - lib/paper_trail_diff/instrumentation.rb
132
131
  - lib/paper_trail_diff/live_association_reader.rb
@@ -135,10 +134,8 @@ files:
135
134
  - lib/paper_trail_diff/live_graph_collector.rb
136
135
  - lib/paper_trail_diff/nested_comparator.rb
137
136
  - lib/paper_trail_diff/net_change.rb
138
- - lib/paper_trail_diff/own_window.rb
139
137
  - lib/paper_trail_diff/paper_trail_adapter.rb
140
138
  - lib/paper_trail_diff/prepared_activity_index.rb
141
- - lib/paper_trail_diff/prepared_association_reifier.rb
142
139
  - lib/paper_trail_diff/prepared_child_candidates.rb
143
140
  - lib/paper_trail_diff/prepared_edge_loader.rb
144
141
  - lib/paper_trail_diff/prepared_history.rb
@@ -151,6 +148,7 @@ files:
151
148
  - lib/paper_trail_diff/recorded_changes_reader.rb
152
149
  - lib/paper_trail_diff/recorded_class.rb
153
150
  - lib/paper_trail_diff/recorded_columns.rb
151
+ - lib/paper_trail_diff/recorded_owner.rb
154
152
  - lib/paper_trail_diff/root_version_plan.rb
155
153
  - lib/paper_trail_diff/root_version_selection.rb
156
154
  - lib/paper_trail_diff/scope_condition.rb
@@ -158,10 +156,13 @@ files:
158
156
  - lib/paper_trail_diff/scoped_analysis.rb
159
157
  - lib/paper_trail_diff/scoped_analysis_builder.rb
160
158
  - lib/paper_trail_diff/scoped_root_selection.rb
159
+ - lib/paper_trail_diff/selection_window.rb
161
160
  - lib/paper_trail_diff/snapshot.rb
161
+ - lib/paper_trail_diff/snapshot_members.rb
162
162
  - lib/paper_trail_diff/snapshot_normalizer.rb
163
163
  - lib/paper_trail_diff/snapshot_traversal.rb
164
164
  - lib/paper_trail_diff/step.rb
165
+ - lib/paper_trail_diff/stored_form.rb
165
166
  - lib/paper_trail_diff/stored_json_values.rb
166
167
  - lib/paper_trail_diff/stored_time_precision.rb
167
168
  - lib/paper_trail_diff/stored_values.rb
@@ -173,11 +174,14 @@ files:
173
174
  - lib/paper_trail_diff/timeline_range.rb
174
175
  - lib/paper_trail_diff/timeline_snapshot_provider.rb
175
176
  - lib/paper_trail_diff/total_order.rb
177
+ - lib/paper_trail_diff/transaction_anchors.rb
176
178
  - lib/paper_trail_diff/transaction_cut.rb
179
+ - lib/paper_trail_diff/transaction_ends.rb
177
180
  - lib/paper_trail_diff/traversal.rb
178
181
  - lib/paper_trail_diff/traversal_emitter.rb
179
182
  - lib/paper_trail_diff/traversal_entry.rb
180
183
  - lib/paper_trail_diff/traversal_preparer.rb
184
+ - lib/paper_trail_diff/unreadable_paths.rb
181
185
  - lib/paper_trail_diff/value_objects.rb
182
186
  - lib/paper_trail_diff/version.rb
183
187
  - lib/paper_trail_diff/version_association_candidate_scope.rb
@@ -208,15 +212,15 @@ files:
208
212
  - sig/generated/paper_trail_diff/activity_scope_filter.rbs
209
213
  - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
210
214
  - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
211
- - sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs
212
215
  - sig/generated/paper_trail_diff/activity_timeline_builder.rbs
216
+ - sig/generated/paper_trail_diff/activity_transaction_applier.rbs
213
217
  - sig/generated/paper_trail_diff/activity_transaction_grouper.rbs
214
218
  - sig/generated/paper_trail_diff/activity_tree_filter.rbs
219
+ - sig/generated/paper_trail_diff/activity_tree_places.rbs
215
220
  - sig/generated/paper_trail_diff/activity_version_collector.rbs
216
221
  - sig/generated/paper_trail_diff/activity_view.rbs
217
222
  - sig/generated/paper_trail_diff/analysis.rbs
218
223
  - sig/generated/paper_trail_diff/analysis_batch.rbs
219
- - sig/generated/paper_trail_diff/approximate_paths.rbs
220
224
  - sig/generated/paper_trail_diff/association_activity_edge.rbs
221
225
  - sig/generated/paper_trail_diff/association_activity_selection.rbs
222
226
  - sig/generated/paper_trail_diff/association_diff_traversal.rbs
@@ -229,6 +233,7 @@ files:
229
233
  - sig/generated/paper_trail_diff/batched_root_analyzer.rbs
230
234
  - sig/generated/paper_trail_diff/batched_root_versions.rbs
231
235
  - sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs
236
+ - sig/generated/paper_trail_diff/candidate_table.rbs
232
237
  - sig/generated/paper_trail_diff/change_attribution.rbs
233
238
  - sig/generated/paper_trail_diff/change_row.rbs
234
239
  - sig/generated/paper_trail_diff/collection_comparator.rbs
@@ -236,6 +241,7 @@ files:
236
241
  - sig/generated/paper_trail_diff/collection_transition.rbs
237
242
  - sig/generated/paper_trail_diff/comparison_batch.rbs
238
243
  - sig/generated/paper_trail_diff/configuration.rbs
244
+ - sig/generated/paper_trail_diff/database_time.rbs
239
245
  - sig/generated/paper_trail_diff/deleted_analysis_batch.rbs
240
246
  - sig/generated/paper_trail_diff/deleted_root_filter.rbs
241
247
  - sig/generated/paper_trail_diff/deprecation.rbs
@@ -244,10 +250,7 @@ files:
244
250
  - sig/generated/paper_trail_diff/endpoint.rbs
245
251
  - sig/generated/paper_trail_diff/engine.rbs
246
252
  - sig/generated/paper_trail_diff/errors.rbs
247
- - sig/generated/paper_trail_diff/fallback_paths.rbs
248
- - sig/generated/paper_trail_diff/habtm_transaction_owners.rbs
249
- - sig/generated/paper_trail_diff/historical_association_reifier.rbs
250
- - sig/generated/paper_trail_diff/historical_filter.rbs
253
+ - sig/generated/paper_trail_diff/exact_column_type.rbs
251
254
  - sig/generated/paper_trail_diff/historical_snapshot_store.rbs
252
255
  - sig/generated/paper_trail_diff/instrumentation.rbs
253
256
  - sig/generated/paper_trail_diff/live_association_reader.rbs
@@ -256,10 +259,8 @@ files:
256
259
  - sig/generated/paper_trail_diff/live_graph_collector.rbs
257
260
  - sig/generated/paper_trail_diff/nested_comparator.rbs
258
261
  - sig/generated/paper_trail_diff/net_change.rbs
259
- - sig/generated/paper_trail_diff/own_window.rbs
260
262
  - sig/generated/paper_trail_diff/paper_trail_adapter.rbs
261
263
  - sig/generated/paper_trail_diff/prepared_activity_index.rbs
262
- - sig/generated/paper_trail_diff/prepared_association_reifier.rbs
263
264
  - sig/generated/paper_trail_diff/prepared_child_candidates.rbs
264
265
  - sig/generated/paper_trail_diff/prepared_edge_loader.rbs
265
266
  - sig/generated/paper_trail_diff/prepared_history.rbs
@@ -272,6 +273,7 @@ files:
272
273
  - sig/generated/paper_trail_diff/recorded_changes_reader.rbs
273
274
  - sig/generated/paper_trail_diff/recorded_class.rbs
274
275
  - sig/generated/paper_trail_diff/recorded_columns.rbs
276
+ - sig/generated/paper_trail_diff/recorded_owner.rbs
275
277
  - sig/generated/paper_trail_diff/root_version_plan.rbs
276
278
  - sig/generated/paper_trail_diff/root_version_selection.rbs
277
279
  - sig/generated/paper_trail_diff/scope_condition.rbs
@@ -279,10 +281,13 @@ files:
279
281
  - sig/generated/paper_trail_diff/scoped_analysis.rbs
280
282
  - sig/generated/paper_trail_diff/scoped_analysis_builder.rbs
281
283
  - sig/generated/paper_trail_diff/scoped_root_selection.rbs
284
+ - sig/generated/paper_trail_diff/selection_window.rbs
282
285
  - sig/generated/paper_trail_diff/snapshot.rbs
286
+ - sig/generated/paper_trail_diff/snapshot_members.rbs
283
287
  - sig/generated/paper_trail_diff/snapshot_normalizer.rbs
284
288
  - sig/generated/paper_trail_diff/snapshot_traversal.rbs
285
289
  - sig/generated/paper_trail_diff/step.rbs
290
+ - sig/generated/paper_trail_diff/stored_form.rbs
286
291
  - sig/generated/paper_trail_diff/stored_json_values.rbs
287
292
  - sig/generated/paper_trail_diff/stored_time_precision.rbs
288
293
  - sig/generated/paper_trail_diff/stored_values.rbs
@@ -294,11 +299,14 @@ files:
294
299
  - sig/generated/paper_trail_diff/timeline_range.rbs
295
300
  - sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs
296
301
  - sig/generated/paper_trail_diff/total_order.rbs
302
+ - sig/generated/paper_trail_diff/transaction_anchors.rbs
297
303
  - sig/generated/paper_trail_diff/transaction_cut.rbs
304
+ - sig/generated/paper_trail_diff/transaction_ends.rbs
298
305
  - sig/generated/paper_trail_diff/traversal.rbs
299
306
  - sig/generated/paper_trail_diff/traversal_emitter.rbs
300
307
  - sig/generated/paper_trail_diff/traversal_entry.rbs
301
308
  - sig/generated/paper_trail_diff/traversal_preparer.rbs
309
+ - sig/generated/paper_trail_diff/unreadable_paths.rbs
302
310
  - sig/generated/paper_trail_diff/value_objects.rbs
303
311
  - sig/generated/paper_trail_diff/version.rbs
304
312
  - sig/generated/paper_trail_diff/version_association_candidate_scope.rbs
@@ -314,11 +322,11 @@ licenses:
314
322
  metadata:
315
323
  allowed_push_host: https://rubygems.org
316
324
  bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
317
- changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.17.0/CHANGELOG.md
318
- documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.17.0/README.md
325
+ changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.18.0/CHANGELOG.md
326
+ documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.18.0/README.md
319
327
  homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
320
328
  rubygems_mfa_required: 'true'
321
- source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.17.0
329
+ source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.18.0
322
330
  rdoc_options: []
323
331
  require_paths:
324
332
  - lib
@@ -1,123 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Loads the `belongs_to` targets owners pointed at from a start onward: at
6
- # the start, after each change since, and in the live row.
7
- #
8
- # PT-AT records a version's foreign keys as they stood after its change, so
9
- # the target at the start comes from the latest version before it. Reading
10
- # only the owners' versions after the start misses a target whose owner did
11
- # not change there -- an author renamed under an article nobody edited.
12
- class ActivityTargetCandidateLoader
13
- # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
14
- # gem supports 3.1.
15
- class Row
16
- attr_reader :owner_id #: untyped
17
- attr_reader :foreign_key_id #: untyped
18
- attr_reader :foreign_type #: String?
19
- attr_reader :created_at #: untyped
20
- attr_reader :event #: String?
21
-
22
- #: (untyped, untyped, String?, ?untyped, ?String?) -> void
23
- def initialize(owner_id, foreign_key_id, foreign_type, created_at = nil, event = nil)
24
- @owner_id = owner_id
25
- @foreign_key_id = foreign_key_id
26
- @foreign_type = foreign_type
27
- @created_at = created_at
28
- @event = event
29
- freeze
30
- end
31
- end
32
-
33
- #: (untyped, Array[untyped], untyped, untyped) -> void
34
- def initialize(owner_class, owner_ids, reflection, start_at)
35
- @owner_class = owner_class
36
- @owner_ids = owner_ids
37
- @reflection = reflection
38
- @start_at = start_at
39
- end
40
-
41
- # Queries shared by a batch's roots keep the owner and timestamp needed to
42
- # partition its candidates back into each root's exact activity range.
43
- #: () -> Array[Row]
44
- def historical_rows
45
- return [] if composite_foreign_key?
46
-
47
- version_class = @owner_class.paper_trail.version_class
48
- scope = VersionAssociationCandidateScope.new(version_class, @start_at)
49
- owner_slices.flat_map do |owners|
50
- relation = scope.call(historical_relation(version_class, owners))
51
- historical_columns(relation, version_class).map do |row|
52
- owner_id, id, type, created_at, event = row
53
- Row.new(Support.record_id(@owner_class, owner_id), id, type, created_at, event)
54
- end
55
- end
56
- end
57
-
58
- # The live row holds the state at a range that ends at the current record.
59
- #: () -> Array[Row]
60
- def current_rows
61
- return [] if composite_foreign_key? || @owner_class.composite_primary_key?
62
-
63
- live_rows.filter_map do |owner_id, id, type|
64
- Row.new(owner_id, id, type) unless id.nil?
65
- end
66
- end
67
-
68
- private
69
-
70
- # @rbs @owner_class: untyped
71
- # @rbs @owner_ids: Array[untyped]
72
- # @rbs @reflection: untyped
73
- # @rbs @start_at: untyped
74
-
75
- # Each statement reads the targets of 500 owners.
76
- #: () -> Enumerator[Array[untyped], untyped]
77
- def owner_slices
78
- @owner_ids.each_slice(Support::IDS_PER_STATEMENT)
79
- end
80
-
81
- #: (untyped, Array[untyped]) -> untyped
82
- def historical_relation(version_class, owners)
83
- VersionTable.joined(association_class, version_class)
84
- .where(foreign_key_name: @reflection.foreign_key)
85
- .where(version_class.table_name => {
86
- item_type: @owner_class.base_class.name, item_id: owners
87
- })
88
- end
89
-
90
- #: (untyped, untyped) -> Array[Array[untyped]]
91
- def historical_columns(relation, version_class)
92
- versions = version_class.arel_table
93
- associations = association_class.arel_table
94
- relation.pluck(versions[:item_id], associations[:foreign_key_id],
95
- associations[:foreign_type], versions[:created_at], versions[:event])
96
- end
97
-
98
- # A polymorphic key names its target in a type column; any other names it
99
- # in the reflection, so no type is read. Like the history, the live read
100
- # takes owners of every class under the base class: a batch can ask for
101
- # the owners of an association through one subclass.
102
- #: () -> Array[Array[untyped]]
103
- def live_rows
104
- key = @reflection.foreign_key
105
- owner_slices.flat_map do |owners|
106
- relation = @owner_class.base_class.unscoped.where(@owner_class.primary_key => owners)
107
- next relation.pluck(@owner_class.primary_key, key) unless @reflection.polymorphic?
108
-
109
- relation.pluck(@owner_class.primary_key, key, @reflection.foreign_type)
110
- end
111
- end
112
-
113
- #: () -> untyped
114
- def association_class
115
- @owner_class.paper_trail.version_association_class
116
- end
117
-
118
- #: () -> bool
119
- def composite_foreign_key?
120
- @reflection.foreign_key.is_a?(Array)
121
- end
122
- end
123
- end
@@ -1,35 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Whether a request may read a path with PT-AT's reifier rather than from
6
- # loaded history. PT-AT places association changes by timestamp alone, so
7
- # only such a path can miss a change between two versions that share one;
8
- # loaded history orders those versions by id.
9
- module FallbackPaths
10
- # A path history reads only approximately counts when it is allowed: a
11
- # request that does not allow it is refused before anything is read.
12
- #: (AssociationTraversal, untyped, approximate: bool) -> bool
13
- def self.any?(traversal, model, approximate:)
14
- return true if approximate && !ApproximatePaths.call(traversal, model).empty?
15
-
16
- traversal.selected_reflections(model).any? { |_path, reflection| per_record?(reflection) }
17
- end
18
-
19
- # Loaded history cannot index a composite foreign key, and a polymorphic
20
- # belongs_to's target, with its default scope, is known only per record.
21
- #: (untyped) -> bool
22
- def self.per_record?(reflection)
23
- composite_key?(reflection) || (reflection.belongs_to? && reflection.polymorphic?)
24
- end
25
- private_class_method :per_record?
26
-
27
- #: (untyped) -> bool
28
- def self.composite_key?(reflection)
29
- [reflection, *AssociationTraversal.through_parts(reflection)].any? do |part|
30
- part.foreign_key.is_a?(Array)
31
- end
32
- end
33
- private_class_method :composite_key?
34
- end
35
- end
@@ -1,70 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # PT-AT records HABTM members under a transaction id and the association's
6
- # name, with nothing naming the record they belong to. When more than one
7
- # record that can own that name saved a version in the transaction, their
8
- # members are mixed together and none of them can be read back.
9
- class HabtmTransactionOwners
10
- #: (untyped, untyped) -> void
11
- def initialize(owner_class, reflection)
12
- @versions = owner_class.paper_trail.version_class
13
- @associations = owner_class.paper_trail.version_association_class
14
- @name = reflection.name.to_s
15
- @owner_types = {} #: Hash[String, bool]
16
- end
17
-
18
- # The given transactions (one id or several) in which more than one
19
- # possible owner saved a version, as strings. Each statement reads up to
20
- # 500 of them.
21
- #: (untyped) -> Array[String]
22
- def shared(transaction_ids)
23
- items = Array(transaction_ids).uniq.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
24
- @versions.where(transaction_id: slice).distinct.pluck(:transaction_id, :item_type, :item_id)
25
- end
26
- owners = items.select { |_, type, _| owner_type?(type) }
27
- owners.group_by { |transaction_id, _, _| transaction_id.to_s }
28
- .filter_map { |transaction_id, rows| transaction_id if rows.size > 1 }
29
- end
30
-
31
- # Members recorded in a shared transaction cannot be told apart. With no
32
- # members recorded, every owner had none, so that reads correctly.
33
- #: (untyped) -> bool
34
- def ambiguous?(transaction_id)
35
- shared(transaction_id).any? &&
36
- @associations.exists?(version_id: transaction_id, foreign_key_name: @name)
37
- end
38
-
39
- #: (untyped) -> void
40
- def ensure_single_owner!(transaction_id)
41
- return unless ambiguous?(transaction_id)
42
-
43
- message = "HABTM history is ambiguous for #{@name} at transaction #{transaction_id}: " \
44
- "more than one record with a #{@name} association saved a version in it, " \
45
- 'and PT-AT does not record which members belong to which record'
46
- raise IncompleteAssociationHistoryError, message
47
- end
48
-
49
- private
50
-
51
- # @rbs @versions: untyped
52
- # @rbs @associations: untyped
53
- # @rbs @name: String
54
- # @rbs @owner_types: Hash[String, bool]
55
-
56
- # Versions name the base class, so a HABTM declared on a subclass counts.
57
- # A type that names no model may have recorded members when it existed.
58
- #: (String) -> bool
59
- def owner_type?(type)
60
- @owner_types.fetch(type) do
61
- model_class = AssociationTraversal.named_class(type)
62
- @owner_types[type] =
63
- !model_class.respond_to?(:reflect_on_association) ||
64
- [model_class, *model_class.descendants].any? do |candidate|
65
- candidate.reflect_on_association(@name)&.macro == :has_and_belongs_to_many
66
- end
67
- end
68
- end
69
- end
70
- end