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
@@ -2,48 +2,92 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Immutable positions for one collection membership and ordering.
5
+ # Finds records in a collection held in type, then ID, order, as an
6
+ # association snapshot holds its records, by searching that order. A table
7
+ # of every record's position would be built again for each event that
8
+ # changed who is in the collection, which made a replay's time grow with
9
+ # its events times the collection's size.
6
10
  class CollectionIdentityIndex
7
- #: (Array[untyped]) -> void
11
+ # A search builds a sort key for each record it looks at, so a collection
12
+ # of up to this many records is quicker to read through. Most nested
13
+ # collections are that small, and a tree is looked through for each event.
14
+ READ_THROUGH = 8
15
+
16
+ #: (Array[RecordSnapshot]) -> void
8
17
  def initialize(records)
9
- @identities = Set.new #: Set[Array[untyped]]
10
- @serialized_positions = {} #: Hash[Array[String], Integer]
11
- @id_positions = {} #: Hash[String, Integer?]
12
- records.each_with_index { |record, index| register(record, index) }
18
+ @records = records
13
19
  freeze
14
20
  end
15
21
 
16
- #: (String, untyped) -> Integer?
22
+ # Ids match by their text: a version's item_id can arrive as a string
23
+ # where the record's id is an integer. The first match in the order is
24
+ # the one found, however it is looked for.
25
+ #: (untyped, untyped) -> Integer?
17
26
  def position(type, id)
18
- @serialized_positions[[type, id.to_s]]
27
+ type = type.to_s
28
+ text = id.to_s
29
+ if @records.length <= READ_THROUGH
30
+ return @records.index { |record| match?(record, type, text) }
31
+ end
32
+
33
+ forms(text).each do |form|
34
+ index = insertion(type, form)
35
+ record = @records.at(index)
36
+ return index if record && match?(record, type, text)
37
+ end
38
+ nil
19
39
  end
20
40
 
41
+ # The position of the only record with this id, whatever its type.
21
42
  #: (untyped) -> Integer?
22
43
  def position_for_id(id)
23
- @id_positions[id.to_s]
44
+ found = nil #: Integer?
45
+ each_type do |type|
46
+ index = position(type, id)
47
+ next unless index
48
+ return if found
49
+
50
+ found = index
51
+ end
52
+ found
53
+ end
54
+
55
+ # Where a record of this type and id is, or would be put to keep the order.
56
+ #: (untyped, untyped) -> Integer
57
+ def insertion(type, id)
58
+ key = Support.sortable_identity(type, id)
59
+ @records.bsearch_index do |record|
60
+ order = Support.sortable_identity(record.type, record.id) <=> key #: Integer
61
+ order >= 0
62
+ end || @records.length
24
63
  end
25
64
 
26
65
  private
27
66
 
28
- # @rbs @identities: Set[Array[untyped]]
29
- # @rbs @serialized_positions: Hash[Array[String], Integer]
30
- # @rbs @id_positions: Hash[String, Integer?]
67
+ # @rbs @records: Array[RecordSnapshot]
31
68
 
32
- #: (untyped, Integer) -> void
33
- def register(record, index)
34
- identity = record.identity
35
- unless @identities.add?(identity)
36
- raise ArgumentError, "duplicate record identity: #{identity}"
37
- end
69
+ #: (RecordSnapshot, String, String) -> bool
70
+ def match?(record, type, text)
71
+ record.type == type && record.id.to_s == text
72
+ end
38
73
 
39
- @serialized_positions[[record.type, record.id.to_s]] = index
40
- register_id(record.id, index)
74
+ # The values an id of this text may be held as, the number first, as
75
+ # records sort a number before the string that prints like it. Text that
76
+ # reads as no number gives nil, which no record found by text matches.
77
+ #: (String) -> Array[untyped]
78
+ def forms(text)
79
+ [Integer(text, exception: false), text]
41
80
  end
42
81
 
43
- #: (untyped, Integer) -> void
44
- def register_id(id, index)
45
- key = id.to_s
46
- @id_positions[key] = (index unless @id_positions.key?(key))
82
+ # Each type the collection holds, found by searching for where the next begins.
83
+ #: () { (String) -> void } -> void
84
+ def each_type
85
+ index = 0
86
+ while index < @records.length
87
+ type = @records.fetch(index).type
88
+ yield type
89
+ index = @records.bsearch_index { |record| record.type > type } || @records.length
90
+ end
47
91
  end
48
92
  end
49
93
  end
@@ -7,7 +7,7 @@ module PaperTrailDiff
7
7
  attr_reader :before #: RecordSnapshot?
8
8
  attr_reader :after #: RecordSnapshot?
9
9
 
10
- # The origin is recorded by serial rather than by reference, because
10
+ # The origin is recorded by its serial rather than by reference, because
11
11
  # holding it would retain every earlier snapshot at the same path for the
12
12
  # whole timeline.
13
13
  #: (from: AssociationSnapshot, before: RecordSnapshot?, after: RecordSnapshot?) -> void
@@ -20,9 +20,9 @@ module PaperTrailDiff
20
20
 
21
21
  #: (AssociationSnapshot) -> bool
22
22
  def from?(association)
23
- @from_serial == association.serial
23
+ @from_serial.equal?(association.serial)
24
24
  end
25
25
 
26
- # @rbs @from_serial: Integer
26
+ # @rbs @from_serial: Object
27
27
  end
28
28
  end
@@ -107,7 +107,7 @@ module PaperTrailDiff
107
107
  live_records.key?(Endpoint.identity(version))
108
108
  end
109
109
  loaded.group_by { |version| RecordedClass.for(version) }.each_value do |versions|
110
- records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }.uniq
110
+ records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }
111
111
  @history_preparer.call(records, versions)
112
112
  end
113
113
  prepare_version_roots!(unloaded)
@@ -119,10 +119,18 @@ module PaperTrailDiff
119
119
  # that later moved to another owner. Such roots are prepared from identity
120
120
  # alone, like deleted ones. Their history still reads the live rows it
121
121
  # needs: a record's current row is its state after its last version.
122
+ #
123
+ # A root's versions share one history, which spans both: a root whose
124
+ # STI class changed between them is prepared as the class of the later.
125
+ # Prepared apart, each history would begin at its own version, and the
126
+ # earlier would miss what changed below the root before the later.
122
127
  #: (Array[untyped]) -> void
123
128
  def prepare_version_roots!(versions)
124
- versions.group_by { |version| RecordedClass.for(version) }.each do |model, group|
125
- ids = group.map(&:item_id).uniq(&:to_s)
129
+ # A pair's versions are in order (see Endpoint.validate_order!).
130
+ roots = versions.group_by { |version| Endpoint.identity(version) }.values
131
+ roots.group_by { |own| RecordedClass.for(own.last) }.each do |model, groups|
132
+ group = groups.flatten
133
+ ids = group.map(&:item_id).uniq
126
134
  @version_history_preparer.call(ids.map { |id| historical_root(model, id) }, group)
127
135
  end
128
136
  end
@@ -137,8 +145,7 @@ module PaperTrailDiff
137
145
 
138
146
  #: (Array[[untyped, untyped]]) -> Array[untyped]
139
147
  def historical_versions(pairs)
140
- selected = pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }
141
- selected.uniq { |version| Support.row_key(version) }
148
+ pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }.uniq
142
149
  end
143
150
 
144
151
  #: () -> Array[[untyped, untyped]]
@@ -162,7 +169,7 @@ module PaperTrailDiff
162
169
  def valid_comparison!(comparison, index)
163
170
  if comparison.is_a?(Hash)
164
171
  keys = comparison.keys.map(&:to_s)
165
- return if keys.sort == %w[from to] && keys.length == 2
172
+ return if keys.sort == %w[from to]
166
173
  end
167
174
 
168
175
  message = "comparisons[#{index}]: must contain exactly from: and to:"
@@ -0,0 +1,85 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Reads a date, or text, given for a datetime column as the database keeps
6
+ # it: in Active Record's default time zone, not Time.zone.
7
+ #
8
+ # Active Record leaves a date assigned to a datetime column on the instance
9
+ # as it was given when time zone aware attributes are off, or when
10
+ # `update_columns` writes it, and PaperTrail stores it from there. The
11
+ # database keeps midnight in its own zone, and `where` sends text or a date
12
+ # to the database as it is. Read through the attribute instead, a date
13
+ # would be midnight in Time.zone, or not a time at all.
14
+ module DatabaseTime
15
+ # A date as JSON writes one, with no time.
16
+ DATE_TEXT = /\A\d{4}-\d{2}-\d{2}\z/
17
+ # The same date in stored text: YAML writes it as a bare value at the
18
+ # end of its line, JSON as quoted text.
19
+ STORED_DATE = /[ "]\d{4}-\d{2}-\d{2}(?:"|$)/
20
+ private_constant :DATE_TEXT, :STORED_DATE
21
+
22
+ # A stored value of a datetime column, with a date in it read as
23
+ # midnight where the database keeps it. A change's values are a pair.
24
+ #: (untyped) -> untyped
25
+ def self.stored(value)
26
+ return value.map { |item| stored(item) } if value.instance_of?(Array)
27
+
28
+ date = value.instance_of?(String) ? written_date(value) : value
29
+ date.instance_of?(Date) ? midnight(date) : value
30
+ end
31
+
32
+ # A date or text given for a datetime column, as the database reads it
33
+ # when `where` sends it: in its own time zone, unless the text names its
34
+ # offset. Anything else, and text that names no time, is returned as it
35
+ # is.
36
+ #: (untyped) -> untyped
37
+ def self.cast(value)
38
+ return midnight(value) if value.instance_of?(Date)
39
+ return value unless value.instance_of?(String)
40
+
41
+ parsed = local? ? Time.parse(value) : Support.constant('ActiveSupport::TimeZone')['UTC'].parse(value)
42
+ parsed || value
43
+ rescue ArgumentError
44
+ value
45
+ end
46
+
47
+ # Whether a version's stored attributes hold a date with no time for a
48
+ # model with a datetime column, which only then is read again.
49
+ #: (untyped, untyped) -> bool
50
+ def self.stored_date?(object, model)
51
+ return false if TimeOfDay.datetime_columns(model).empty?
52
+ return STORED_DATE.match?(object) if object.instance_of?(String)
53
+
54
+ object.respond_to?(:each_value) &&
55
+ object.each_value.any? { |value| value.instance_of?(String) && DATE_TEXT.match?(value) }
56
+ end
57
+
58
+ # A Date; the packaged signatures name only core types.
59
+ #: (untyped) -> Time
60
+ def self.midnight(date)
61
+ clock = Time #: untyped
62
+ if local?
63
+ clock.local(date.year, date.month,
64
+ date.day)
65
+ else
66
+ clock.utc(date.year, date.month, date.day)
67
+ end
68
+ end
69
+ private_class_method :midnight
70
+
71
+ #: () -> bool
72
+ def self.local?
73
+ Support.constant('ActiveRecord').default_timezone == :local
74
+ end
75
+ private_class_method :local?
76
+
77
+ #: (String) -> untyped
78
+ def self.written_date(text)
79
+ Date.iso8601(text) if DATE_TEXT.match?(text)
80
+ rescue ArgumentError
81
+ nil
82
+ end
83
+ private_class_method :written_date
84
+ end
85
+ end
@@ -6,20 +6,18 @@ module PaperTrailDiff
6
6
  class DeletedAnalysisBatch
7
7
  # `context_required` reads a root that did not change in the window from
8
8
  # the version after it, so its associations' activity can be reported.
9
- # `traversal` names the requested paths, which decide where a window's
10
- # edges move (see TransactionCut).
11
- #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, traversal: AssociationTraversal?) -> void
9
+ #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool, reach: untyped) -> void
12
10
  def initialize( # rubocop:disable Metrics/ParameterLists
13
11
  model, identities:, time_range:, analyzer:, history_preparer:, version_scope:,
14
- context_required:, traversal:
12
+ context_required:, reach:
15
13
  )
16
14
  @model = model
17
- @traversal = traversal
18
15
  @context_required = context_required
19
16
  @identities = identities
20
17
  @time_range = time_range
21
18
  @analyzer = analyzer
22
19
  @history_preparer = history_preparer
20
+ @reach = reach
23
21
  @version_scope = version_scope
24
22
  end
25
23
 
@@ -27,11 +25,11 @@ module PaperTrailDiff
27
25
  def call
28
26
  destroys = destroy_versions
29
27
  records = historical_roots(destroys)
30
- windows = TransactionCut.batch_windows(records, @time_range, traversal: @traversal)
31
28
  analyses = BatchedRootAnalyses.new(
32
- time_range: @time_range, windows: windows, history_preparer: @history_preparer,
33
- analyzer: @analyzer
34
- ).call(records, plans(records, destroys, windows))
29
+ time_range: @time_range, planner: ->(roots, range) { plans(roots, destroys, range) },
30
+ history_preparer: @history_preparer, analyzer: @analyzer,
31
+ activity: @context_required, reach: @reach
32
+ ).call(records)
35
33
  with_unavailable(analyses)
36
34
  end
37
35
 
@@ -43,34 +41,35 @@ module PaperTrailDiff
43
41
  end
44
42
 
45
43
  # @rbs @model: untyped
46
- # @rbs @traversal: AssociationTraversal?
47
44
  # @rbs @context_required: bool
48
45
  # @rbs @identities: Array[Array[String]]
49
46
  # @rbs @time_range: TimeRange?
50
47
  # @rbs @analyzer: untyped
51
48
  # @rbs @history_preparer: untyped
49
+ # @rbs @reach: untyped
52
50
  # @rbs @version_scope: untyped
53
51
 
54
- # A root destroyed before the window had no state inside it to read, so
55
- # only the others take the version after the window as context. Every
56
- # root replays the whole of its window for activity on associations: one
57
- # whose destroy saved in a transaction that crossed the window's start
58
- # has the destroy inside its moved window.
59
- #: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
60
- def plans(records, destroys, windows)
61
- start = @time_range&.begin_time
52
+ # A root destroyed before the range had no state inside it to read, so
53
+ # only the others take the version after the range as context. Every
54
+ # root replays the whole of its range for activity on associations. The
55
+ # range is the window, or the window widened to where the transactions
56
+ # open at its start began, which can hold a destroy that one of them saved.
57
+ #: (Array[untyped], Array[untyped], TimeRange?) -> Hash[Array[String], RootVersionPlan]
58
+ def plans(records, destroys, range)
59
+ start = range&.begin_time
62
60
  early = destroys.select { |version| start && version.created_at < start }
63
61
  .map { |version| version.item_id.to_s }
64
62
  before, during = records.partition { |record| early.include?(record.id.to_s) }
65
- plans_for(during, @context_required, windows).merge(plans_for(before, false, windows))
63
+ plans_for(during, @context_required, range)
64
+ .merge(plans_for(before, false, range))
66
65
  end
67
66
 
68
- #: (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
69
- def plans_for(records, context_required, windows)
67
+ #: (Array[untyped], bool, TimeRange?) -> Hash[Array[String], RootVersionPlan]
68
+ def plans_for(records, context_required, range)
70
69
  BatchedRootVersions.new(
71
- records, time_range: @time_range, version_scope: @version_scope,
70
+ records, time_range: range, version_scope: @version_scope,
72
71
  live_endpoints: nil, context_required: context_required,
73
- whole: @context_required, windows: windows
72
+ whole: @context_required
74
73
  ).call
75
74
  end
76
75
 
@@ -15,7 +15,8 @@ module PaperTrailDiff
15
15
  raise ConfigurationError,
16
16
  'include_deleted: cannot test deleted records against this relation: its ' \
17
17
  "conditions must be equality, IN, NULL, or range tests on #{model.name}'s " \
18
- 'own columns, and a range or a text comparison must be on a column whose ' \
18
+ 'own columns that its history records, and a range or a text comparison ' \
19
+ 'must be on a column whose ' \
19
20
  'values compare in Ruby as the database compares them, as for an ' \
20
21
  'association scope; select deleted records some other way'
21
22
  end
@@ -39,11 +40,8 @@ module PaperTrailDiff
39
40
  def call(identities)
40
41
  return [] if @condition.none?
41
42
 
42
- states = destroyed_states(identities.map(&:last))
43
- identities.select do |identity|
44
- id = identity.last
45
- !states.key?(id) || selected?(states.fetch(id))
46
- end
43
+ selected = selected(identities.map(&:last))
44
+ identities.select { |identity| selected.fetch(identity.last, true) }
47
45
  end
48
46
 
49
47
  private
@@ -60,6 +58,12 @@ module PaperTrailDiff
60
58
  @relation.model
61
59
  end
62
60
 
61
+ # Whether the relation selects each root its destroy recorded, by id.
62
+ #: (Array[String]) -> Hash[String, bool]
63
+ def selected(ids)
64
+ destroyed_states(ids).transform_values { |attributes| selected?(attributes) }
65
+ end
66
+
63
67
  #: (Hash[String, untyped]?) -> bool
64
68
  def selected?(attributes)
65
69
  return false unless attributes
@@ -65,21 +65,20 @@ module PaperTrailDiff
65
65
 
66
66
  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
67
67
  #
68
- # The endpoints are a comparison's: two versions, or a version and the
69
- # current record, in either order. Two current records read no history, so
68
+ # The endpoints are a comparison's: two versions in time order, or a
69
+ # version and the current record, in either order. Two current records read no history, so
70
70
  # nothing is checked.
71
71
  class HistoryDiagnostics
72
72
  STOPPING_CODES = %i[
73
73
  unknown_association unsupported_association association_tracking_unavailable
74
74
  ].freeze
75
75
 
76
- #: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
77
- def initialize(from, to, associations:, allow_approximate: false)
76
+ #: (untyped, untyped, associations: association_option) -> void
77
+ def initialize(from, to, associations:)
78
78
  @versions = validated_versions(from, to)
79
79
  @tree = AssociationTree.build(associations)
80
80
  @traversal = AssociationTraversal.new(@tree)
81
- @preparer = TraversalPreparer.new(traversal: @traversal, allow_approximate: allow_approximate)
82
- @allow_approximate = allow_approximate
81
+ @preparer = TraversalPreparer.new(traversal: @traversal)
83
82
  @issues = [] #: Array[DiagnosticIssue]
84
83
  end
85
84
 
@@ -87,11 +86,15 @@ module PaperTrailDiff
87
86
  def call
88
87
  unless @versions.empty?
89
88
  model_class = Endpoint.model_class(@versions.fetch(0))
89
+ # Nothing else can be read from a history without states.
90
+ stateless = Support.stateless_reason(model_class)
91
+ return report_stateless(stateless) if stateless
92
+
90
93
  ReadSnapshot.call([model_class]) do
91
94
  # Runs whether or not associations are selected: unorderable versions
92
95
  # corrupt a scalar timeline just as surely, and a report that inspected
93
96
  # nothing has no business answering `ok?`.
94
- inspect_version_sequence(model_class)
97
+ inspect_version_sequence
95
98
  inspect_associations(model_class) unless @tree.empty?
96
99
  end
97
100
  end
@@ -111,19 +114,17 @@ module PaperTrailDiff
111
114
 
112
115
  selected = @traversal.selected_reflections(model_class)
113
116
  inspect_polymorphic_targets(selected)
114
- inspect_approximate_paths(model_class) if @allow_approximate
115
117
  inspect_checkpoint_timestamp(model_class)
116
- inspect_habtm(model_class, selected)
117
118
  end
118
119
 
119
120
  # @rbs @versions: Array[untyped]
120
121
  # @rbs @tree: AssociationTree
121
122
  # @rbs @traversal: AssociationTraversal
122
123
  # @rbs @preparer: TraversalPreparer
123
- # @rbs @allow_approximate: bool
124
124
  # @rbs @issues: Array[DiagnosticIssue]
125
125
 
126
- # The endpoints that are versions, in the order given.
126
+ # The endpoints that are versions, in the order given. Endpoints that
127
+ # `compare` rejects whatever their history raise as it would.
127
128
  #: (untyped, untyped) -> Array[untyped]
128
129
  def validated_versions(from, to)
129
130
  Endpoint.validate!(from)
@@ -132,6 +133,8 @@ module PaperTrailDiff
132
133
  raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
133
134
  end
134
135
 
136
+ Endpoint.validate_order!(from, to)
137
+
135
138
  [from, to].select { |endpoint| Endpoint.version?(endpoint) }
136
139
  end
137
140
 
@@ -144,63 +147,12 @@ module PaperTrailDiff
144
147
  end
145
148
  end
146
149
 
147
- # Accepted, but read the way `allow_approximate:` describes.
148
- #: (untyped) -> void
149
- def inspect_approximate_paths(model_class)
150
- ApproximatePaths.call(@traversal, model_class).each do |path, reason|
151
- add_warning(:approximate_association,
152
- "association #{path} is read approximately with PT-AT (#{reason}): a " \
153
- 'record that entered or left it since is reported wrongly', path)
154
- end
155
- end
156
-
157
- #: (untyped, Array[Array[untyped]]) -> void
158
- def inspect_habtm(model_class, selected)
159
- habtm = selected.select { |_, reflection| reflection.macro == :has_and_belongs_to_many }
160
- return if habtm.empty?
161
-
162
- inspect_transaction_metadata(habtm.map(&:first))
163
- inspect_shared_transactions(model_class, habtm)
164
- end
165
-
166
- # PT-AT does not record which owner a HABTM member belongs to, so a
167
- # transaction that more than one owner recorded members in cannot be read.
168
- #: (untyped, Array[Array[untyped]]) -> void
169
- def inspect_shared_transactions(model_class, habtm)
170
- versions = @versions.select { |version| VersionBoundary.transaction_id(version) }
171
- habtm.each do |path, reflection|
172
- owners = HabtmTransactionOwners.new(model_class, reflection)
173
- versions.each do |version|
174
- next unless owners.ambiguous?(version.transaction_id)
175
-
176
- add_error(:habtm_transaction_shared,
177
- 'HABTM endpoint shares its transaction with another owner of the association',
178
- path, version.id)
179
- end
180
- end
181
- end
182
-
183
150
  # With the current record as one endpoint there is one version, and the
184
151
  # sequence runs on from it.
185
- #: (untyped) -> void
186
- def inspect_version_sequence(model_class)
152
+ #: () -> void
153
+ def inspect_version_sequence
187
154
  first, last = @versions
188
- @issues.concat(
189
- VersionSequenceDiagnostics.new(first, last,
190
- fallback_selected: fallback_selected?(model_class)).call
191
- )
192
- end
193
-
194
- # Only a path PT-AT reads can lose a change between tied versions, and a
195
- # traversal that does not resolve reads nothing at all.
196
- #: (untyped) -> bool
197
- def fallback_selected?(model_class)
198
- return false if @tree.empty?
199
-
200
- refusals = @preparer.refusals(model_class, historical: true)
201
- return false if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
202
-
203
- FallbackPaths.any?(@traversal, model_class, approximate: @allow_approximate)
155
+ @issues.concat(VersionSequenceDiagnostics.new(first, last).call)
204
156
  end
205
157
 
206
158
  #: (untyped) -> void
@@ -211,24 +163,6 @@ module PaperTrailDiff
211
163
  add_warning(:synchronized_version_timestamp, message)
212
164
  end
213
165
 
214
- #: (Array[String]) -> void
215
- def inspect_transaction_metadata(paths)
216
- @versions.each do |version|
217
- if !version.respond_to?(:transaction_id)
218
- add_error(:transaction_id_column_missing, 'version has no transaction_id column')
219
- elsif version.transaction_id.nil?
220
- paths.each do |path|
221
- add_error(
222
- :transaction_id_missing,
223
- 'HABTM endpoint has no transaction-backed association snapshot',
224
- path,
225
- version.id
226
- )
227
- end
228
- end
229
- end
230
- end
231
-
232
166
  #: (untyped) -> bool
233
167
  def synchronized_timestamp_disabled?(model_class)
234
168
  options = model_class.paper_trail_options
@@ -237,9 +171,15 @@ module PaperTrailDiff
237
171
  false
238
172
  end
239
173
 
240
- #: (Symbol, String, ?String?, ?untyped) -> void
241
- def add_error(code, message, path = nil, version_id = nil)
242
- add_issue(:error, code, message, path, version_id)
174
+ #: (String) -> DiagnosticReport
175
+ def report_stateless(reason)
176
+ add_error(:stateless_versions, reason)
177
+ DiagnosticReport.new(issues: @issues)
178
+ end
179
+
180
+ #: (Symbol, String, ?String?) -> void
181
+ def add_error(code, message, path = nil)
182
+ add_issue(:error, code, message, path, nil)
243
183
  end
244
184
 
245
185
  #: (Symbol, String, ?String?) -> void
@@ -12,6 +12,9 @@ module PaperTrailDiff
12
12
  raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
13
13
  end
14
14
 
15
+ version = [from_endpoint, to_endpoint].find { |endpoint| version?(endpoint) }
16
+ ReadableHistory.check_model!(model_class(version)) if version
17
+
15
18
  validate_order!(from_endpoint, to_endpoint)
16
19
  end
17
20
 
@@ -40,22 +43,26 @@ module PaperTrailDiff
40
43
 
41
44
  #: (untyped) -> void
42
45
  def self.validate!(endpoint)
43
- return if version?(endpoint)
46
+ return ReadableHistory.check_version!(endpoint) if version?(endpoint)
44
47
 
45
48
  validate_record!(endpoint)
46
49
  end
47
50
 
48
51
  # The record a method reads the history of: a record, saved or destroyed,
49
- # of a model PaperTrail versions.
52
+ # of a model PaperTrail versions, or one PaperTrail rebuilt. A saved
53
+ # record's history ends at its row, so unsaved changes to it have no place
54
+ # in it, with or without a window.
50
55
  #: (untyped) -> void
51
56
  def self.validate_root!(record)
52
57
  unless record?(record)
53
58
  raise InvalidEndpointError, "expected a record, got #{described(record)}"
54
59
  end
55
- return if Support.versioned?(record.class)
60
+ if record.persisted? && record.respond_to?(:has_changes_to_save?) &&
61
+ record.has_changes_to_save?
62
+ raise InvalidEndpointError, 'record must not have unsaved changes'
63
+ end
56
64
 
57
- raise InvalidEndpointError,
58
- "#{record.class} is not versioned, so it has no history: add has_paper_trail to it"
65
+ ReadableHistory.check_model!(record.class)
59
66
  end
60
67
 
61
68
  # What a message names the value as. A relation is named rather than
@@ -151,6 +158,31 @@ module PaperTrailDiff
151
158
  private_class_method :validate_record!
152
159
  end
153
160
 
161
+ # Whether a history can be read: of a model, and from a version given.
162
+ module ReadableHistory
163
+ #: (untyped) -> void
164
+ def self.check_model!(model_class)
165
+ unless Support.versioned?(model_class)
166
+ raise InvalidEndpointError,
167
+ "#{model_class} is not versioned, so it has no history: add has_paper_trail to it"
168
+ end
169
+ reason = Support.stateless_reason(model_class)
170
+ raise ConfigurationError, reason if reason
171
+ end
172
+
173
+ # A version read with `select` can lack the column its state, or its
174
+ # changes, are in.
175
+ #: (untyped, ?String) -> void
176
+ def self.check_version!(version, column = 'object')
177
+ return unless version.respond_to?(:has_attribute?) && version.class.respond_to?(:column_names)
178
+ return if version.has_attribute?(column) || !version.class.column_names.include?(column)
179
+
180
+ raise InvalidEndpointError,
181
+ "version #{version.id} was loaded without its #{column} column; " \
182
+ 'load versions with all their columns'
183
+ end
184
+ end
185
+
154
186
  # Whether a value is a version, a record, or neither, answered once for
155
187
  # each Active Record class (see Support.per_model).
156
188
  module EndpointKind
@@ -28,7 +28,7 @@ module PaperTrailDiff
28
28
  (from_attributes.keys | to_attributes.keys).sort.each do |name|
29
29
  from_value = from_attributes[name]
30
30
  to_value = to_attributes[name]
31
- next if from_value == to_value
31
+ next if Support.same?(from_value, to_value)
32
32
 
33
33
  changes[name] = ValueChange.new(from: from_value, to: to_value)
34
34
  end