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
@@ -1,161 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Reconstructs selected nested edges at one root PaperTrail endpoint.
6
- class HistoricalAssociationReifier
7
- #: (untyped, ?habtm_version: untyped) -> void
8
- def initialize(version, habtm_version: version)
9
- @transaction_id = VersionBoundary.transaction_id(version)
10
- @habtm_transaction_id = VersionBoundary.transaction_id(habtm_version)
11
- @version_at = version.created_at
12
- # Keyed on record identity rather than `object_id`, which Ruby may reuse
13
- # once an earlier record in the same pass has been collected.
14
- reified = {} #: Hash[untyped, Hash[untyped, bool]]
15
- @reified_associations = reified.compare_by_identity
16
- end
17
-
18
- #: (untyped, Array[untyped]) -> void
19
- def reify(record, reflections)
20
- reflections.each { |reflection| reify_association(record, reflection) }
21
- end
22
-
23
- private
24
-
25
- # @rbs @transaction_id: untyped
26
- # @rbs @habtm_transaction_id: untyped
27
- # @rbs @version_at: untyped
28
- # @rbs @reified_associations: Hash[untyped, Hash[untyped, bool]]
29
-
30
- #: (untyped, untyped) -> void
31
- def reify_association(record, reflection)
32
- reified = @reified_associations[record] ||= {} #: Hash[untyped, bool]
33
- return if reified[reflection.name]
34
-
35
- reified[reflection.name] = true
36
- case reflection.macro
37
- when :belongs_to
38
- reify_belongs_to(record, reflection)
39
- when :has_one
40
- reifier(:HasOne).reify(reflection, record, options, @transaction_id)
41
- when :has_many
42
- reify_has_many(record, reflection)
43
- when :has_and_belongs_to_many
44
- reify_habtm(record, reflection)
45
- end
46
- end
47
-
48
- #: (untyped, untyped) -> void
49
- def reify_belongs_to(record, reflection)
50
- ensure_versioned_target!(record, reflection) if reflection.polymorphic?
51
- reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
52
- end
53
-
54
- # A polymorphic target's class is known only from the record's type
55
- # column, so TraversalPreparer cannot check it is versioned up front.
56
- #: (untyped, untyped) -> void
57
- def ensure_versioned_target!(record, reflection)
58
- model_class = AssociationTraversal.belongs_to_target(reflection, record)
59
- return if model_class.nil? || Support.versioned?(model_class)
60
-
61
- raise UnversionedAssociationError,
62
- "association #{record.class.name}##{reflection.name} cannot be compared " \
63
- "historically: it points at #{model_class.name}, which is not versioned. Add " \
64
- "`has_paper_trail` to #{model_class.name}, or mirror the fields you need onto a " \
65
- 'model that has it.'
66
- end
67
-
68
- #: (untyped, untyped) -> void
69
- def reify_has_many(record, reflection)
70
- if reflection.options[:through]
71
- reify_association(record, reflection.through_reflection)
72
- reify_through(record, reflection)
73
- return
74
- end
75
-
76
- version_table = record.class.paper_trail.version_class.table_name
77
- reifier(:HasMany).reify(
78
- reflection,
79
- record,
80
- options,
81
- @transaction_id,
82
- version_table
83
- )
84
- end
85
-
86
- # PT-AT's collection-source helper reifies every has_many on each join
87
- # record. Walk only the requested source instead, including nested throughs.
88
- #: (untyped, untyped) -> void
89
- def reify_through(record, reflection)
90
- source = reflection.source_reflection
91
- if pt_at_source?(reflection)
92
- reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
93
- return
94
- end
95
-
96
- members = through_members(record, reflection, source)
97
- association = record.association(reflection.name)
98
- association.target = members.uniq do |member|
99
- Support.record_identity(member.class, member.id)
100
- end
101
- association.loaded!
102
- end
103
-
104
- # PT-AT's belongs_to source ignores `source_type:` and reads targets by id
105
- # alone, so a typed through walks its join records instead.
106
- #: (untyped) -> bool
107
- def pt_at_source?(reflection)
108
- reflection.source_reflection.belongs_to? && !reflection.options[:source_type]
109
- end
110
-
111
- #: (untyped, untyped, untyped) -> Array[untyped]
112
- def through_members(record, reflection, source)
113
- joins = Array(record.public_send(reflection.through_reflection.name)) #: Array[untyped]
114
- joins = joins.select { |join| AssociationTraversal.source_type_join?(reflection, join) }
115
- joins.flat_map do |join|
116
- reify_association(join, source)
117
- Array(join.public_send(source.name))
118
- end
119
- end
120
-
121
- #: (untyped, untyped) -> void
122
- def reify_habtm(record, reflection)
123
- unless @habtm_transaction_id
124
- message = 'HABTM reconstruction requires a transaction-backed endpoint version'
125
- raise IncompleteAssociationHistoryError, message
126
- end
127
- HabtmTransactionOwners.new(record.class, reflection)
128
- .ensure_single_owner!(@habtm_transaction_id)
129
-
130
- paper_trail = Object.const_get(:PaperTrail) #: untyped
131
- target_versioned = paper_trail.request.enabled_for_model?(reflection.klass)
132
- reifier(:HasAndBelongsToMany).reify(
133
- target_versioned,
134
- reflection,
135
- record,
136
- options,
137
- @habtm_transaction_id
138
- )
139
- end
140
-
141
- #: () -> Hash[Symbol, untyped]
142
- def options
143
- {
144
- dup: true,
145
- mark_for_destruction: false,
146
- unversioned_attributes: :nil,
147
- version_at: @version_at
148
- }
149
- end
150
-
151
- #: (Symbol) -> untyped
152
- def reifier(name)
153
- tracking = Object.const_get(:PaperTrailAssociationTracking) #: untyped
154
- reifiers = tracking.const_get(:Reifiers) #: untyped
155
- reifiers.const_get(name)
156
- rescue NameError => e
157
- message = 'loaded association tracking does not support nested reconstruction'
158
- raise AssociationTrackingUnavailableError, message, cause: e
159
- end
160
- end
161
- end
@@ -1,210 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Selects roots by the values they held at any point in the window, with an
6
- # explicit ceiling on version loading.
7
- #
8
- # A version records the state *before* its own change, so the versions in
9
- # the window supply the state at its start and after every change but the
10
- # last. The state after the last change lives in the first version after
11
- # the window, or in the live row when nothing follows; a destroy leaves none.
12
- #
13
- # Each candidate is read over the window its analysis covers, which a
14
- # transaction crossing an edge moves (see TransactionCut). `windows` gives
15
- # the moved ones, keyed by id, for a slice of candidates and the window.
16
- class HistoricalFilter
17
- DEFAULT_VERSION_LIMIT = 10_000
18
-
19
- #: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer, windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]) -> void
20
- def initialize(model, predicate:, time_range:, limit:, max_versions:, windows:) # rubocop:disable Metrics/ParameterLists
21
- @model = model
22
- @predicate = validate_predicate(predicate)
23
- @time_range = time_range
24
- @limit = limit
25
- @max_versions = validate_budget(max_versions)
26
- @windows = windows
27
- @loaded = 0
28
- @state_loader = PreparedVersionStateLoader.new
29
- end
30
-
31
- # More matches than the limit raise, unless the caller does not count
32
- # them: candidates it only lists, such as deleted roots.
33
- #: (Array[String], ?counted: bool) -> Array[String]
34
- def call(candidates, counted: true)
35
- matched = [] #: Array[String]
36
- candidates.each_slice(Support::IDS_PER_STATEMENT) do |slice|
37
- versions, past = own_versions(slice)
38
- closing = closing_states(slice, versions, past)
39
- slice.each do |id|
40
- next unless held?(versions.fetch(id, []), closing[id])
41
-
42
- matched << id
43
- reject_root_limit! if counted && matched.length > @limit
44
- end
45
- end
46
- matched
47
- end
48
-
49
- private
50
-
51
- # @rbs @model: untyped
52
- # @rbs @predicate: untyped
53
- # @rbs @time_range: TimeRange?
54
- # @rbs @limit: Integer
55
- # @rbs @max_versions: Integer
56
- # @rbs @windows: ^(Array[String], TimeRange) -> Hash[String, TimeRange]
57
- # @rbs @loaded: Integer
58
- # @rbs @state_loader: PreparedVersionStateLoader
59
-
60
- #: (untyped) -> untyped
61
- def validate_predicate(predicate)
62
- return predicate if predicate.respond_to?(:call)
63
- unless predicate.is_a?(Hash)
64
- raise ConfigurationError, 'historical_filter: must respond to call or be an attribute hash'
65
- end
66
-
67
- attributes = predicate.transform_keys(&:to_s)
68
- unknown = attributes.keys - @model.attribute_names
69
- if unknown.any?
70
- raise ConfigurationError,
71
- "unknown historical attributes: #{unknown.join(', ')}"
72
- end
73
-
74
- attributes.to_h { |name, value| [name, cast(name, value)] }
75
- end
76
-
77
- # Expected and recorded values compare as the attribute casts them, as
78
- # `where` reads its values: an enum's symbol names its stored value, and a
79
- # `json` or `jsonb` version column, which PaperTrail does not cast, holds
80
- # dates and times as strings. Casting also copies a mutable value, so the
81
- # filter keeps its own.
82
- #: (String, untyped) -> untyped
83
- def cast(name, value)
84
- @model.type_for_attribute(name).cast(value)
85
- end
86
-
87
- #: (untyped) -> Integer
88
- def validate_budget(value)
89
- return value if value.instance_of?(Integer) && value.positive?
90
-
91
- raise ConfigurationError, 'max_filter_versions: must be a positive Integer'
92
- end
93
-
94
- # Each candidate's versions in its own window, read from the earliest
95
- # moved start, and the first past each end that moved.
96
- #: (Array[String]) -> [Hash[String, Array[untyped]], Hash[String, untyped]]
97
- def own_versions(ids)
98
- range = @time_range
99
- past = {} #: Hash[String, untyped]
100
- return [candidate_versions(ids, nil), past] unless range
101
-
102
- windows = @windows.call(ids, range)
103
- loaded = candidate_versions(ids, OwnWindow.widest(range, windows.values))
104
- own = loaded.to_h do |id, versions|
105
- inside, past[id] = OwnWindow.split(windows.fetch(id, range), versions)
106
- [id, inside]
107
- end
108
- [own, past]
109
- end
110
-
111
- #: (Array[String], TimeRange?) -> Hash[String, Array[untyped]]
112
- def candidate_versions(ids, range)
113
- relation = VersionQuery.for_items(@model, ids)
114
- relation = range.scope(relation) if range
115
- # One past the remaining budget is enough to know it was exceeded.
116
- versions = VersionQuery.chronological(relation).limit(@max_versions - @loaded + 1)
117
- account_versions!(versions.length)
118
- versions.group_by { |version| version.item_id.to_s }
119
- end
120
-
121
- #: (Array[untyped], untyped) -> boolish
122
- def held?(versions, closing)
123
- return true if versions.any? { |version| matches?(version) }
124
- return false unless closing
125
-
126
- Endpoint.version?(closing) ? matches?(closing) : record_matches?(closing)
127
- end
128
-
129
- # What each candidate held after its last change in the window: the
130
- # first version past an end that moved, read already, or past the end as
131
- # asked, or the live row.
132
- #: (Array[String], Hash[String, Array[untyped]], Hash[String, untyped]) -> Hash[String, untyped]
133
- def closing_states(ids, versions, past)
134
- open = ids.reject { |id| versions.fetch(id, []).last&.event == 'destroy' }
135
- ended = past.slice(*open).compact
136
- rest = open - ended.keys
137
- trailing = trailing_versions(rest)
138
- ended.merge(trailing, live_records(rest - trailing.keys))
139
- end
140
-
141
- #: (Array[String]) -> Hash[String, untyped]
142
- def trailing_versions(ids)
143
- range = @time_range
144
- return {} unless range
145
-
146
- trailing = range.first_trailing_versions(VersionQuery.for_items(@model, ids))
147
- account_versions!(trailing.length)
148
- trailing
149
- end
150
-
151
- #: (Array[String]) -> Hash[String, untyped]
152
- def live_records(ids)
153
- @model.unscoped.where(@model.primary_key => ids).to_h { |record| [record.id.to_s, record] }
154
- end
155
-
156
- #: (untyped) -> boolish
157
- def record_matches?(record)
158
- return @predicate.call(record) unless @predicate.instance_of?(Hash)
159
-
160
- @predicate.all? { |name, expected| record.attributes.fetch(name) == expected }
161
- end
162
-
163
- #: (Integer) -> void
164
- def account_versions!(count)
165
- @loaded += count
166
- return unless @loaded > @max_versions
167
-
168
- raise FilterLimitExceededError,
169
- "historical_filter: exceeds max_filter_versions: #{@max_versions}; " \
170
- 'narrow the window or explicitly increase the version budget'
171
- end
172
-
173
- #: (untyped) -> boolish
174
- def matches?(version)
175
- if @predicate.instance_of?(Hash)
176
- return false unless version.object
177
-
178
- return attributes_match?(version)
179
- end
180
-
181
- state = Support.reify(version, dup: true)
182
- state && @predicate.call(state)
183
- end
184
-
185
- #: (untyped) -> bool
186
- def attributes_match?(version)
187
- state = @state_loader.call(version)
188
- unless state
189
- raise ConfigurationError,
190
- 'historical_filter: cannot read recorded attributes directly; use a bounded callable'
191
- end
192
-
193
- @predicate.all? do |name, expected|
194
- unless state.attributes.key?(name)
195
- raise ConfigurationError,
196
- "historical_filter: #{name} was not recorded in version #{version.id}"
197
- end
198
-
199
- cast(name, state.attributes.fetch(name)) == expected
200
- end
201
- end
202
-
203
- #: () -> void
204
- def reject_root_limit!
205
- raise BatchLimitExceededError,
206
- "historical_filter: matched more than #{@limit} roots; narrow the window " \
207
- 'or the filter, or raise limit: to the population you intend to analyze'
208
- end
209
- end
210
- end
@@ -1,35 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Splits the versions read for a batch by each root's own window. A
6
- # transaction that crosses an edge moves a root's window to start or end
7
- # earlier (see TransactionCut), never later, so the versions read from the
8
- # earliest start to the shared end hold each root's own, and the first left
9
- # past an end that moved.
10
- module OwnWindow
11
- # From the earliest start to the shared end.
12
- #: (TimeRange, Array[TimeRange]) -> TimeRange
13
- def self.widest(range, windows)
14
- start = [range.begin_time, *windows.map(&:begin_time)].min
15
- TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
16
- end
17
-
18
- # The versions inside `window`, and the first of the rest past its end.
19
- # They are read in no order, so the first is found by time and id.
20
- #: (TimeRange, Array[untyped]) -> [Array[untyped], untyped]
21
- def self.split(window, loaded)
22
- own, rest = loaded.partition { |version| window.include?(version.created_at) }
23
- [own, first_past(rest, window.end_time)]
24
- end
25
-
26
- #: (Array[untyped], Time?) -> untyped
27
- def self.first_past(versions, finish)
28
- return unless finish
29
-
30
- versions.select { |version| version.created_at >= finish }
31
- .min_by { |version| Support.chronological_version_key(version) }
32
- end
33
- private_class_method :first_past
34
- end
35
- end
@@ -1,51 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Resolves indexed associations and delegates unsupported reflections to PT-AT.
6
- class PreparedAssociationReifier
7
- #: (PreparedHistory, untyped, habtm_boundary: untyped, fallback: HistoricalAssociationReifier) -> void
8
- def initialize(history, boundary, habtm_boundary:, fallback:)
9
- @history = history
10
- @boundary = boundary
11
- @habtm_boundary = habtm_boundary
12
- @fallback = fallback
13
- # Keyed on record identity rather than `object_id`, which Ruby may reuse
14
- # once an earlier record in the same pass has been collected.
15
- reified = {} #: Hash[untyped, Hash[untyped, bool]]
16
- @reified = reified.compare_by_identity
17
- end
18
-
19
- #: (untyped, Array[untyped]) -> void
20
- def reify(record, reflections)
21
- reflections.each { |reflection| reify_association(record, reflection) }
22
- end
23
-
24
- private
25
-
26
- # @rbs @history: PreparedHistory
27
- # @rbs @boundary: untyped
28
- # @rbs @habtm_boundary: untyped
29
- # @rbs @fallback: HistoricalAssociationReifier
30
- # @rbs @reified: Hash[untyped, Hash[untyped, bool]]
31
-
32
- #: (untyped, untyped) -> void
33
- def reify_association(record, reflection)
34
- reified = @reified[record] ||= {} #: Hash[untyped, bool]
35
- return if reified[reflection.name]
36
-
37
- reified[reflection.name] = true
38
- handled, records = @history.resolve(
39
- record,
40
- reflection,
41
- @boundary,
42
- habtm_boundary: @habtm_boundary
43
- )
44
- return @fallback.reify(record, [reflection]) unless handled
45
-
46
- association = record.association(reflection.name)
47
- association.target = reflection.collection? ? records : records.first
48
- association.loaded!
49
- end
50
- end
51
- end
@@ -1,74 +0,0 @@
1
- # Generated from lib/paper_trail_diff/activity_target_candidate_loader.rb with RBS::Inline
2
-
3
- module PaperTrailDiff
4
- # Loads the `belongs_to` targets owners pointed at from a start onward: at
5
- # the start, after each change since, and in the live row.
6
- #
7
- # PT-AT records a version's foreign keys as they stood after its change, so
8
- # the target at the start comes from the latest version before it. Reading
9
- # only the owners' versions after the start misses a target whose owner did
10
- # not change there -- an author renamed under an article nobody edited.
11
- class ActivityTargetCandidateLoader
12
- # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
13
- # gem supports 3.1.
14
- class Row
15
- attr_reader owner_id: untyped
16
-
17
- attr_reader foreign_key_id: untyped
18
-
19
- attr_reader foreign_type: String?
20
-
21
- attr_reader created_at: untyped
22
-
23
- attr_reader event: String?
24
-
25
- # : (untyped, untyped, String?, ?untyped, ?String?) -> void
26
- def initialize: (untyped, untyped, String?, ?untyped, ?String?) -> void
27
- end
28
-
29
- # : (untyped, Array[untyped], untyped, untyped) -> void
30
- def initialize: (untyped, Array[untyped], untyped, untyped) -> void
31
-
32
- # Queries shared by a batch's roots keep the owner and timestamp needed to
33
- # partition its candidates back into each root's exact activity range.
34
- # : () -> Array[Row]
35
- def historical_rows: () -> Array[Row]
36
-
37
- # The live row holds the state at a range that ends at the current record.
38
- # : () -> Array[Row]
39
- def current_rows: () -> Array[Row]
40
-
41
- private
42
-
43
- @owner_class: untyped
44
-
45
- @owner_ids: Array[untyped]
46
-
47
- @reflection: untyped
48
-
49
- @start_at: untyped
50
-
51
- # Each statement reads the targets of 500 owners.
52
- # : () -> Enumerator[Array[untyped], untyped]
53
- def owner_slices: () -> Enumerator[Array[untyped], untyped]
54
-
55
- # : (untyped, Array[untyped]) -> untyped
56
- def historical_relation: (untyped, Array[untyped]) -> untyped
57
-
58
- # : (untyped, untyped) -> Array[Array[untyped]]
59
- def historical_columns: (untyped, untyped) -> Array[Array[untyped]]
60
-
61
- # A polymorphic key names its target in a type column; any other names it
62
- # in the reflection, so no type is read. Like the history, the live read
63
- # takes owners of every class under the base class: a batch can ask for
64
- # the owners of an association through one subclass.
65
- # : () -> Array[Array[untyped]]
66
- def live_rows: () -> Array[Array[untyped]]
67
-
68
- # : () -> untyped
69
- def association_class: () -> untyped
70
-
71
- # : () -> bool
72
- def composite_foreign_key?: () -> bool
73
- end
74
- end
@@ -1,22 +0,0 @@
1
- # Generated from lib/paper_trail_diff/fallback_paths.rb with RBS::Inline
2
-
3
- module PaperTrailDiff
4
- # Whether a request may read a path with PT-AT's reifier rather than from
5
- # loaded history. PT-AT places association changes by timestamp alone, so
6
- # only such a path can miss a change between two versions that share one;
7
- # loaded history orders those versions by id.
8
- module FallbackPaths
9
- # A path history reads only approximately counts when it is allowed: a
10
- # request that does not allow it is refused before anything is read.
11
- # : (AssociationTraversal, untyped, approximate: bool) -> bool
12
- def self.any?: (AssociationTraversal, untyped, approximate: bool) -> bool
13
-
14
- # Loaded history cannot index a composite foreign key, and a polymorphic
15
- # belongs_to's target, with its default scope, is known only per record.
16
- # : (untyped) -> bool
17
- def self.per_record?: (untyped) -> bool
18
-
19
- # : (untyped) -> bool
20
- def self.composite_key?: (untyped) -> bool
21
- end
22
- end
@@ -1,41 +0,0 @@
1
- # Generated from lib/paper_trail_diff/habtm_transaction_owners.rb with RBS::Inline
2
-
3
- module PaperTrailDiff
4
- # PT-AT records HABTM members under a transaction id and the association's
5
- # name, with nothing naming the record they belong to. When more than one
6
- # record that can own that name saved a version in the transaction, their
7
- # members are mixed together and none of them can be read back.
8
- class HabtmTransactionOwners
9
- # : (untyped, untyped) -> void
10
- def initialize: (untyped, untyped) -> void
11
-
12
- # The given transactions (one id or several) in which more than one
13
- # possible owner saved a version, as strings. Each statement reads up to
14
- # 500 of them.
15
- # : (untyped) -> Array[String]
16
- def shared: (untyped) -> Array[String]
17
-
18
- # Members recorded in a shared transaction cannot be told apart. With no
19
- # members recorded, every owner had none, so that reads correctly.
20
- # : (untyped) -> bool
21
- def ambiguous?: (untyped) -> bool
22
-
23
- # : (untyped) -> void
24
- def ensure_single_owner!: (untyped) -> void
25
-
26
- private
27
-
28
- @associations: untyped
29
-
30
- @name: String
31
-
32
- @owner_types: Hash[String, bool]
33
-
34
- @versions: untyped
35
-
36
- # Versions name the base class, so a HABTM declared on a subclass counts.
37
- # A type that names no model may have recorded members when it existed.
38
- # : (String) -> bool
39
- def owner_type?: (String) -> bool
40
- end
41
- end
@@ -1,58 +0,0 @@
1
- # Generated from lib/paper_trail_diff/historical_association_reifier.rb with RBS::Inline
2
-
3
- module PaperTrailDiff
4
- # Reconstructs selected nested edges at one root PaperTrail endpoint.
5
- class HistoricalAssociationReifier
6
- # : (untyped, ?habtm_version: untyped) -> void
7
- def initialize: (untyped, ?habtm_version: untyped) -> void
8
-
9
- # : (untyped, Array[untyped]) -> void
10
- def reify: (untyped, Array[untyped]) -> void
11
-
12
- private
13
-
14
- @habtm_transaction_id: untyped
15
-
16
- @reified_associations: Hash[untyped, Hash[untyped, bool]]
17
-
18
- @transaction_id: untyped
19
-
20
- @version_at: untyped
21
-
22
- # : (untyped, untyped) -> void
23
- def reify_association: (untyped, untyped) -> void
24
-
25
- # : (untyped, untyped) -> void
26
- def reify_belongs_to: (untyped, untyped) -> void
27
-
28
- # A polymorphic target's class is known only from the record's type
29
- # column, so TraversalPreparer cannot check it is versioned up front.
30
- # : (untyped, untyped) -> void
31
- def ensure_versioned_target!: (untyped, untyped) -> void
32
-
33
- # : (untyped, untyped) -> void
34
- def reify_has_many: (untyped, untyped) -> void
35
-
36
- # PT-AT's collection-source helper reifies every has_many on each join
37
- # record. Walk only the requested source instead, including nested throughs.
38
- # : (untyped, untyped) -> void
39
- def reify_through: (untyped, untyped) -> void
40
-
41
- # PT-AT's belongs_to source ignores `source_type:` and reads targets by id
42
- # alone, so a typed through walks its join records instead.
43
- # : (untyped) -> bool
44
- def pt_at_source?: (untyped) -> bool
45
-
46
- # : (untyped, untyped, untyped) -> Array[untyped]
47
- def through_members: (untyped, untyped, untyped) -> Array[untyped]
48
-
49
- # : (untyped, untyped) -> void
50
- def reify_habtm: (untyped, untyped) -> void
51
-
52
- # : () -> Hash[Symbol, untyped]
53
- def options: () -> Hash[Symbol, untyped]
54
-
55
- # : (Symbol) -> untyped
56
- def reifier: (Symbol) -> untyped
57
- end
58
- end