paper_trail_diff 0.13.0 → 0.14.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 (121) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +318 -0
  3. data/QUICKSTART.md +9 -6
  4. data/README.md +84 -9
  5. data/docs/architecture.md +32 -9
  6. data/docs/performance.md +106 -13
  7. data/docs/reference.md +242 -29
  8. data/docs/testing.md +55 -9
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  11. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  12. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  15. data/lib/paper_trail_diff/activity_range.rb +14 -2
  16. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  18. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  19. data/lib/paper_trail_diff/activity_timeline_builder.rb +30 -24
  20. data/lib/paper_trail_diff/activity_version_collector.rb +31 -20
  21. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  22. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  23. data/lib/paper_trail_diff/association_discovery.rb +8 -13
  24. data/lib/paper_trail_diff/association_traversal.rb +169 -45
  25. data/lib/paper_trail_diff/batch_safety.rb +23 -15
  26. data/lib/paper_trail_diff/batched_root_versions.rb +21 -39
  27. data/lib/paper_trail_diff/collection_comparator.rb +18 -20
  28. data/lib/paper_trail_diff/collection_identity_index.rb +8 -12
  29. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  30. data/lib/paper_trail_diff/deleted_analysis_batch.rb +36 -17
  31. data/lib/paper_trail_diff/diagnostics.rb +26 -8
  32. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  33. data/lib/paper_trail_diff/errors.rb +2 -1
  34. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  35. data/lib/paper_trail_diff/historical_association_reifier.rb +32 -2
  36. data/lib/paper_trail_diff/historical_filter.rb +12 -17
  37. data/lib/paper_trail_diff/historical_snapshot_store.rb +6 -9
  38. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +35 -2
  39. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  40. data/lib/paper_trail_diff/paper_trail_adapter.rb +22 -6
  41. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +1 -1
  42. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  43. data/lib/paper_trail_diff/prepared_edge_loader.rb +29 -45
  44. data/lib/paper_trail_diff/prepared_history.rb +63 -54
  45. data/lib/paper_trail_diff/prepared_history_loader.rb +33 -43
  46. data/lib/paper_trail_diff/prepared_record_index.rb +26 -0
  47. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  48. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  49. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  50. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  51. data/lib/paper_trail_diff/root_version_plan.rb +10 -1
  52. data/lib/paper_trail_diff/scope_condition.rb +331 -0
  53. data/lib/paper_trail_diff/scope_ranking.rb +196 -0
  54. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  55. data/lib/paper_trail_diff/scoped_root_selection.rb +93 -43
  56. data/lib/paper_trail_diff/snapshot.rb +5 -1
  57. data/lib/paper_trail_diff/snapshot_normalizer.rb +50 -47
  58. data/lib/paper_trail_diff/support.rb +9 -4
  59. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -1
  60. data/lib/paper_trail_diff/time_range.rb +9 -13
  61. data/lib/paper_trail_diff/time_version_range.rb +6 -6
  62. data/lib/paper_trail_diff/timeline_range.rb +5 -4
  63. data/lib/paper_trail_diff/version.rb +1 -1
  64. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  65. data/lib/paper_trail_diff/version_query.rb +9 -1
  66. data/lib/paper_trail_diff/version_range.rb +8 -15
  67. data/lib/paper_trail_diff/version_scope_filter.rb +11 -3
  68. data/lib/paper_trail_diff.rb +31 -2
  69. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  70. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  71. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  72. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  73. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -2
  74. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  75. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  76. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  77. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +11 -5
  78. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +10 -4
  79. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  80. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  81. data/sig/generated/paper_trail_diff/association_discovery.rbs +3 -5
  82. data/sig/generated/paper_trail_diff/association_traversal.rbs +84 -9
  83. data/sig/generated/paper_trail_diff/batch_safety.rbs +10 -4
  84. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -8
  85. data/sig/generated/paper_trail_diff/collection_comparator.rbs +6 -3
  86. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +3 -3
  87. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  88. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +16 -4
  89. data/sig/generated/paper_trail_diff/diagnostics.rbs +7 -2
  90. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  91. data/sig/generated/paper_trail_diff/errors.rbs +2 -1
  92. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  93. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  94. data/sig/generated/paper_trail_diff/historical_filter.rbs +6 -6
  95. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +3 -2
  96. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +17 -0
  97. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  99. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  100. data/sig/generated/paper_trail_diff/prepared_history.rbs +33 -22
  101. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  102. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +15 -0
  103. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  104. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  105. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  106. data/sig/generated/paper_trail_diff/root_version_plan.rbs +7 -0
  107. data/sig/generated/paper_trail_diff/scope_condition.rbs +185 -0
  108. data/sig/generated/paper_trail_diff/scope_ranking.rbs +117 -0
  109. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  110. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +41 -7
  111. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +25 -9
  112. data/sig/generated/paper_trail_diff/support.rbs +5 -2
  113. data/sig/generated/paper_trail_diff/time_range.rbs +4 -0
  114. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  115. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -1
  116. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  117. data/sig/generated/paper_trail_diff/version_query.rbs +7 -1
  118. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  119. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -0
  120. data/sig/generated/paper_trail_diff.rbs +21 -2
  121. metadata +20 -4
@@ -43,12 +43,20 @@ module PaperTrailDiff
43
43
  end
44
44
  end
45
45
 
46
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
47
- def initialize(scope, time_range:, limit:, historical_filter: nil,
48
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT)
46
+ # `activity_tree` names the association paths whose changes also select a
47
+ # root, as an activity analysis reports them. Without one, only a root's
48
+ # own versions select it.
49
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
50
+ def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
51
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
49
52
  @scope = normalize_scope(scope)
53
+ reject_unversioned!
50
54
  @time_range = time_range
51
55
  @limit = validate_limit(limit)
56
+ @related = if activity_tree
57
+ AssociationActivitySelection.new(model, tree: activity_tree,
58
+ time_range: time_range)
59
+ end
52
60
  @historical_filter = unless historical_filter.nil?
53
61
  HistoricalFilter.new(base_class, predicate: historical_filter,
54
62
  time_range: time_range, limit: @limit,
@@ -58,17 +66,11 @@ module PaperTrailDiff
58
66
 
59
67
  #: () -> Result
60
68
  def call
61
- return database_selection if @historical_filter.nil? && comparable_keys?
69
+ related = @related&.call || []
70
+ queries = subqueries(related)
71
+ return database_selection(queries) if queries
62
72
 
63
- candidates = versioned_ids
64
- candidates = @historical_filter.call(candidates) if @historical_filter && candidates.any?
65
- return Result.new(records: [], unreachable: []) if candidates.empty?
66
-
67
- live = live_ids(candidates)
68
- Result.new(
69
- records: selected_records(live),
70
- unreachable: (candidates - live).map { |id| identity(id) }.freeze
71
- )
73
+ plucked_selection(versioned_ids | AssociationActivitySelection.values(related).map(&:to_s))
72
74
  end
73
75
 
74
76
  private
@@ -77,38 +79,67 @@ module PaperTrailDiff
77
79
  # @rbs @time_range: TimeRange?
78
80
  # @rbs @limit: Integer
79
81
  # @rbs @historical_filter: untyped
82
+ # @rbs @related: AssociationActivitySelection?
80
83
 
81
84
  # Leaves the candidate set in the database. Plucking every root changed in
82
85
  # the window would cost memory and a statement proportional to all activity
83
86
  # in the window -- not to the relation or `limit:` -- so a report on one
84
87
  # record could read every id in a busy table. A subquery keeps the work
85
88
  # bounded by what the relation and the deletions actually contain.
86
- #: () -> Result
87
- def database_selection
88
- candidates = window_versions.select(:item_id)
89
+ #: (Array[AssociationActivitySelection::Query]) -> Result
90
+ def database_selection(related)
91
+ candidates = [window_versions.select(:item_id)] + related.map(&:relation)
92
+ missing = (missing_ids + related_missing_ids(related)).uniq.sort
89
93
  Result.new(
90
94
  records: selected_records(candidates),
91
- unreachable: missing_ids.map { |id| identity(id) }.freeze
95
+ unreachable: missing.map { |id| identity(id) }.freeze
96
+ )
97
+ end
98
+
99
+ # Comparing in SQL needs every subquery's column to share the key's type.
100
+ #: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
101
+ def subqueries(related)
102
+ return unless @historical_filter.nil? && comparable_keys?
103
+
104
+ queries = related.grep(AssociationActivitySelection::Query) #: Array[AssociationActivitySelection::Query]
105
+ matching = queries.select { |ids| ids.type == key_type }
106
+ matching if matching.length == related.length
107
+ end
108
+
109
+ #: (Array[String]) -> Result
110
+ def plucked_selection(candidates)
111
+ candidates = @historical_filter.call(candidates) if @historical_filter
112
+ live = live_ids(candidates)
113
+ Result.new(
114
+ records: selected_records([live]),
115
+ unreachable: (candidates - live).sort.map { |id| identity(id) }.freeze
92
116
  )
93
117
  end
94
118
 
95
119
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
96
- # rejects an integer key against a string item_id outright.
120
+ # rejects an integer key against a string item_id outright. A composite
121
+ # key names no single attribute, so it has no type and never matches.
97
122
  #: () -> bool
98
123
  def comparable_keys?
99
- return false unless primary_key.is_a?(String)
124
+ version_class.type_for_attribute('item_id').type == key_type
125
+ end
126
+
127
+ #: () -> Symbol?
128
+ def key_type
129
+ base_class.type_for_attribute(primary_key).type
130
+ end
100
131
 
101
- item_id = version_class.columns_hash['item_id']&.type
102
- key = base_class.columns_hash[primary_key]&.type
103
- !item_id.nil? && item_id == key
132
+ #: (Array[AssociationActivitySelection::Query]) -> Array[String]
133
+ def related_missing_ids(related)
134
+ live = base_class.unscoped.select(primary_key).arel
135
+ related.flat_map { |ids| ids.missing(live) }.map(&:to_s)
104
136
  end
105
137
 
106
138
  # Changed in the window but without a row, found with an anti-join instead
107
139
  # of comparing two plucked lists.
108
140
  #: () -> Array[String]
109
141
  def missing_ids
110
- live = base_class.unscoped.select(primary_key)
111
- window_versions.where.not(item_id: live).distinct.pluck(:item_id).map(&:to_s).uniq.sort
142
+ window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
112
143
  end
113
144
 
114
145
  #: () -> untyped
@@ -127,16 +158,21 @@ module PaperTrailDiff
127
158
  raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
128
159
  end
129
160
 
130
- relation = scope.all
131
- return relation if Support.versioned?(relation.model)
161
+ scope.all
162
+ end
163
+
164
+ #: () -> void
165
+ def reject_unversioned!
166
+ return if Support.versioned?(model)
132
167
 
133
168
  raise UnversionedAssociationError,
134
- "scope: #{relation.model.name} is not versioned, so it has no history to select from"
169
+ "scope: #{model} is not versioned, so it has no history to select from"
135
170
  end
136
171
 
172
+ # No Integer subclass has instances, so this is `is_a?` by another name.
137
173
  #: (Integer) -> Integer
138
174
  def validate_limit(limit)
139
- return limit if limit.is_a?(Integer) && limit.positive?
175
+ return limit if limit.instance_of?(Integer) && limit.positive?
140
176
 
141
177
  raise ConfigurationError, 'limit: must be a positive Integer'
142
178
  end
@@ -146,7 +182,7 @@ module PaperTrailDiff
146
182
  # version table alone so that it does not depend on rows still existing.
147
183
  #: () -> Array[String]
148
184
  def versioned_ids
149
- window_versions.distinct.pluck(:item_id).map(&:to_s).uniq
185
+ window_versions.distinct.pluck(:item_id).map(&:to_s)
150
186
  end
151
187
 
152
188
  # Which of those candidates still have a row, asked without the relation's
@@ -161,14 +197,15 @@ module PaperTrailDiff
161
197
  # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
162
198
  # relation may order by joined columns or select a PostgreSQL json column.
163
199
  # Read bounded pages until the relation ends or too many unique roots appear.
164
- #: (untyped) -> Array[untyped]
165
- def selected_records(live)
166
- return [] if live.is_a?(Array) && live.empty?
167
-
200
+ # Each candidate source is an id list or a subquery; a record matching any
201
+ # of them is selected.
202
+ #: (Array[untyped]) -> Array[untyped]
203
+ def selected_records(candidates)
204
+ relation = candidate_relation(candidates)
168
205
  records = {} #: Hash[untyped, untyped]
169
206
  consumed = 0
170
207
  loop do
171
- page = record_page(live, consumed)
208
+ page = record_page(relation, consumed)
172
209
  page.each { |record| records[record.id] ||= record }
173
210
  reject_oversized!(records.length)
174
211
  break if page.length < PAGE_SIZE
@@ -178,15 +215,20 @@ module PaperTrailDiff
178
215
  records.values.freeze
179
216
  end
180
217
 
218
+ #: (Array[untyped]) -> untyped
219
+ def candidate_relation(candidates)
220
+ candidates.map do |ids|
221
+ conditions = { primary_key => ids } #: Hash[untyped, untyped]
222
+ ordered_scope.where(conditions)
223
+ end.reduce(:or)
224
+ end
225
+
181
226
  #: (untyped, Integer) -> Array[untyped]
182
- def record_page(live, consumed)
227
+ def record_page(relation, consumed)
183
228
  count = page_limit(consumed)
184
229
  return [] if count.zero?
185
230
 
186
- # An id list or a candidate subquery; both read the same way in SQL.
187
- conditions = { primary_key => live } #: Hash[untyped, untyped]
188
- ordered_scope.where(conditions)
189
- .offset((@scope.offset_value || 0) + consumed).limit(count).to_a
231
+ relation.offset((@scope.offset_value || 0) + consumed).limit(count)
190
232
  end
191
233
 
192
234
  # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
@@ -220,22 +262,30 @@ module PaperTrailDiff
220
262
 
221
263
  #: () -> String
222
264
  def item_type
223
- base_class.name.to_s
265
+ base_class.name
266
+ end
267
+
268
+ # A relation delegates class methods to its model, so every mutation here,
269
+ # which drops `.model`, answers the same.
270
+ # mutant:disable
271
+ #: () -> untyped
272
+ def model
273
+ @scope.model
224
274
  end
225
275
 
226
276
  #: () -> untyped
227
277
  def base_class
228
- @scope.model.base_class
278
+ model.base_class
229
279
  end
230
280
 
231
281
  #: () -> untyped
232
282
  def primary_key
233
- @scope.model.primary_key
283
+ model.primary_key
234
284
  end
235
285
 
236
286
  #: () -> untyped
237
287
  def version_class
238
- @scope.model.paper_trail.version_class
288
+ model.paper_trail.version_class
239
289
  end
240
290
  end
241
291
  end
@@ -171,7 +171,11 @@ module PaperTrailDiff
171
171
 
172
172
  #: (type: String, id: untyped, attributes: snapshot_attributes, ?associations: snapshot_associations) -> void
173
173
  def initialize(type:, id:, attributes:, associations: {})
174
- @type = Support.immutable_copy(type.to_s)
174
+ unless type.is_a?(String)
175
+ raise ArgumentError, "record type must be a String, not #{type.inspect}"
176
+ end
177
+
178
+ @type = Support.immutable_copy(type)
175
179
  @id = Support.immutable_copy(id)
176
180
  @identity = [@type, @id].freeze
177
181
  @attributes = normalize_hash(attributes)
@@ -21,9 +21,7 @@ module PaperTrailDiff
21
21
  #: (String, AssociationSnapshot) -> AssociationSnapshot
22
22
  def association(path, snapshot)
23
23
  previous = @associations[path]
24
- if previous && previous.kind == snapshot.kind && previous.records == snapshot.records
25
- return previous
26
- end
24
+ return previous if previous && same_association?(previous, snapshot)
27
25
 
28
26
  @associations[path] = snapshot
29
27
  end
@@ -38,10 +36,14 @@ module PaperTrailDiff
38
36
  left.attributes == right.attributes &&
39
37
  left.associations.keys == right.associations.keys &&
40
38
  left.associations.all? do |name, association|
41
- other = right.associations[name]
42
- other && association.kind == other.kind && association.records == other.records
39
+ same_association?(association, right.associations.fetch(name))
43
40
  end
44
41
  end
42
+
43
+ #: (AssociationSnapshot, AssociationSnapshot) -> bool
44
+ def same_association?(left, right)
45
+ left.kind == right.kind && left.records == right.records
46
+ end
45
47
  end
46
48
 
47
49
  # Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
@@ -53,11 +55,13 @@ module PaperTrailDiff
53
55
  @traversal = traversal
54
56
  @pool = pool
55
57
  @structural_columns = {} #: Hash[String, Array[String]]
56
- @excluded_attributes = {} #: Hash[Array[untyped], Array[String]]
58
+ @excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
57
59
  end
58
60
 
59
61
  #: (untyped, reifier: untyped) -> RecordSnapshot?
60
62
  def call(record, reifier:)
63
+ return unless record
64
+
61
65
  reflections = reflections_for(record, @tree, '')
62
66
  normalize_record(record, @tree, '', reifier, reflections)
63
67
  end
@@ -76,7 +80,7 @@ module PaperTrailDiff
76
80
  # Normalizes scalar attributes without traversing or loading associations.
77
81
  #: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
78
82
  def attributes_for(record, tree:, path:)
79
- if record.is_a?(PreparedRecordState)
83
+ if record.instance_of?(PreparedRecordState)
80
84
  return from_state(record, tree: tree,
81
85
  path: path).attributes
82
86
  end
@@ -94,7 +98,7 @@ module PaperTrailDiff
94
98
  excluded = @excluded_attributes[[model, path]] ||=
95
99
  build_excluded_attributes(model, reflections, path)
96
100
  snapshot = RecordSnapshot.new(
97
- type: model.name, id: state.attributes[model.primary_key],
101
+ type: model.name, id: state_id(model, state),
98
102
  attributes: state.attributes.except(*excluded), associations: associations
99
103
  )
100
104
  pool_state(path, snapshot)
@@ -102,6 +106,14 @@ module PaperTrailDiff
102
106
 
103
107
  private
104
108
 
109
+ # The id a live record of the same row reports: one value, or one per
110
+ # column of a composite key.
111
+ #: (untyped, PreparedRecordState) -> untyped
112
+ def state_id(model, state)
113
+ key = model.primary_key
114
+ key.instance_of?(Array) ? state.attributes.fetch_values(*key) : state.attributes.fetch(key)
115
+ end
116
+
105
117
  #: (String, RecordSnapshot) -> RecordSnapshot
106
118
  def pool_state(path, snapshot)
107
119
  path.empty? ? snapshot : @pool.record(path, snapshot)
@@ -112,12 +124,10 @@ module PaperTrailDiff
112
124
  # @rbs @traversal: AssociationTraversal
113
125
  # @rbs @pool: SnapshotPool
114
126
  # @rbs @structural_columns: Hash[String, Array[String]]
115
- # @rbs @excluded_attributes: Hash[Array[untyped], Array[String]]
127
+ # @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
116
128
 
117
- #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot?
129
+ #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
118
130
  def normalize_record(record, tree, path, reifier, reflections)
119
- return unless record
120
-
121
131
  snapshot = RecordSnapshot.new(
122
132
  type: record.class.name,
123
133
  id: record.id,
@@ -129,7 +139,7 @@ module PaperTrailDiff
129
139
 
130
140
  #: (untyped, Array[untyped], String) -> snapshot_attributes
131
141
  def normalized_attributes(record, reflections, path)
132
- attributes = record.attributes.dup
142
+ attributes = record.attributes
133
143
  excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
134
144
  StoredTimePrecision.apply(attributes, StoredTimePrecision.digits(record.class))
135
145
  end
@@ -137,23 +147,20 @@ module PaperTrailDiff
137
147
  # Every input is fixed for one model class at one selected path, and the
138
148
  # path's structural columns are recorded before its records normalize, so
139
149
  # this is resolved once instead of per record per boundary.
140
- #: (untyped, Array[untyped], String) -> Array[String]
150
+ #: (untyped, Array[untyped], String) -> Array[String?]
141
151
  def excluded_attributes(record, reflections, path)
142
152
  model_class = record.class
143
153
  @excluded_attributes[[model_class, path]] ||=
144
154
  build_excluded_attributes(model_class, reflections, path)
145
155
  end
146
156
 
147
- #: (untyped, Array[untyped], String) -> Array[String]
157
+ #: (untyped, Array[untyped], String) -> Array[String?]
148
158
  def build_excluded_attributes(model_class, reflections, path)
149
- primary_key = model_class.primary_key #: untyped
150
- primary_keys = primary_key.is_a?(Array) ? primary_key : [primary_key]
151
- # @type var primary_keys: Array[untyped]
152
- primary_keys = primary_keys.map { |key| key.to_s } # rubocop:disable Style/SymbolProc
159
+ primary_keys = Array(model_class.primary_key) #: Array[String]
153
160
  ignored = @ignore_policy.attributes_for(path)
154
161
  structural = @structural_columns.fetch(path, [])
155
- (primary_keys + ignored + skipped_columns(model_class) +
156
- relationship_columns(reflections) + structural).uniq.freeze
162
+ primary_keys + ignored + skipped_columns(model_class) +
163
+ relationship_columns(reflections) + structural
157
164
  end
158
165
 
159
166
  # `has_paper_trail skip:` columns are never written to a version, so history
@@ -163,18 +170,17 @@ module PaperTrailDiff
163
170
  def skipped_columns(model_class)
164
171
  return [] unless Support.versioned?(model_class)
165
172
 
166
- entries = Array(model_class.paper_trail_options[:skip]) #: Array[untyped]
167
- entries.flat_map do |entry|
168
- entry.is_a?(Hash) ? entry.keys.map(&:to_s) : [entry.to_s]
169
- end
173
+ # PaperTrail stores these as strings, or hashes keyed by strings.
174
+ entries = model_class.paper_trail_options.fetch(:skip) #: Array[untyped]
175
+ entries.flat_map { |entry| entry.instance_of?(Hash) ? entry.keys : entry }
170
176
  end
171
177
 
172
- #: (Array[untyped]) -> Array[String]
178
+ # A non-polymorphic reflection has no foreign type, so it adds nil, which
179
+ # excludes nothing.
180
+ #: (Array[untyped]) -> Array[String?]
173
181
  def relationship_columns(reflections)
174
182
  reflections.select { |reflection| reflection.macro == :belongs_to }.flat_map do |reflection|
175
- columns = [reflection.foreign_key.to_s]
176
- columns << reflection.foreign_type.to_s if reflection.polymorphic?
177
- columns
183
+ [reflection.foreign_key, reflection.foreign_type]
178
184
  end
179
185
  end
180
186
 
@@ -182,28 +188,20 @@ module PaperTrailDiff
182
188
  def normalize_associations(record, tree, path, reifier, reflections)
183
189
  reflections.to_h do |reflection|
184
190
  name = reflection.name.to_s
185
- subtree = tree.child(name)
186
- raise ConfigurationError, "missing traversal subtree: #{name}" unless subtree
187
-
188
- [name, association_snapshot(record, reflection, subtree, path, reifier)]
191
+ [name, association_snapshot(record, reflection, tree.children.fetch(name), path, reifier)]
189
192
  end
190
193
  end
191
194
 
192
195
  #: (untyped, untyped, AssociationTree, String, untyped) -> AssociationSnapshot
193
- def association_snapshot( # rubocop:disable Metrics/AbcSize
196
+ def association_snapshot(
194
197
  record,
195
198
  reflection,
196
199
  subtree,
197
200
  path,
198
201
  reifier
199
202
  )
200
- associated = record.public_send(reflection.name)
201
- records = if AssociationSnapshot.collection_kind?(reflection.macro)
202
- associated.to_a
203
- else
204
- Array(associated).compact
205
- end
206
- child_path = Support.association_path(path, reflection.name.to_s)
203
+ records = members(record, reflection)
204
+ child_path = Support.association_path(path, reflection.name)
207
205
  @structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
208
206
  snapshot = AssociationSnapshot.new(
209
207
  kind: reflection.macro,
@@ -212,12 +210,19 @@ module PaperTrailDiff
212
210
  @pool.association(child_path, snapshot)
213
211
  end
214
212
 
213
+ # A reified history can hold a member PaperTrail could not rebuild. A
214
+ # through loads a record once per join that reaches it; it is one member,
215
+ # as Active Record compares records by class and id.
216
+ #: (untyped, untyped) -> Array[untyped]
217
+ def members(record, reflection)
218
+ Array(record.public_send(reflection.name)).compact.uniq
219
+ end
220
+
215
221
  #: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
216
222
  def normalize_children(records, tree, path, reifier)
217
- reflections_by_class = {} #: Hash[String, Array[untyped]]
218
- records.filter_map do |child|
219
- type = child.class.name
220
- reflections = reflections_by_class[type] ||= reflections_for(child, tree, path)
223
+ reflections_by_class = {} #: Hash[untyped, Array[untyped]]
224
+ records.map do |child|
225
+ reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
221
226
  reifier.reify(child, reflections) unless reflections.empty?
222
227
  normalize_record(child, tree, path, reifier, reflections)
223
228
  end
@@ -225,8 +230,6 @@ module PaperTrailDiff
225
230
 
226
231
  #: (untyped, AssociationTree, String) -> Array[untyped]
227
232
  def reflections_for(record, tree, path)
228
- return [] unless record
229
-
230
233
  @traversal.reflections_for(record.class, tree, path: path)
231
234
  end
232
235
  end
@@ -3,7 +3,7 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Internal helpers for isolating and serializing values held by result objects.
6
- module Support
6
+ module Support # rubocop:disable Metrics/ModuleLength
7
7
  module_function
8
8
 
9
9
  #: (untyped) -> untyped
@@ -46,7 +46,12 @@ module PaperTrailDiff
46
46
 
47
47
  #: (untyped) -> Array[untyped]
48
48
  def chronological_version_key(version)
49
- [version.created_at, version.id.to_s.rjust(32, '0')]
49
+ version_key(version.created_at, version.id)
50
+ end
51
+
52
+ #: (untyped, untyped) -> Array[untyped]
53
+ def version_key(created_at, id)
54
+ [created_at, id.to_s.rjust(32, '0')]
50
55
  end
51
56
 
52
57
  # Ordering falls back to the id whenever timestamps tie, which recovers the
@@ -124,9 +129,9 @@ module PaperTrailDiff
124
129
  raise(ConfigurationError, 'versions have incomparable timestamps')
125
130
  end
126
131
 
127
- #: (String, String) -> String
132
+ #: (String, String | Symbol) -> String
128
133
  def association_path(parent, name)
129
- parent.empty? ? name : "#{parent}.#{name}"
134
+ parent.empty? ? name.to_s : "#{parent}.#{name}"
130
135
  end
131
136
 
132
137
  #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
@@ -194,7 +194,6 @@ module PaperTrailDiff
194
194
  @record,
195
195
  root_versions: root_versions,
196
196
  tree: @tree,
197
- traversal: AssociationTraversal.new(@tree),
198
197
  prepared: (@snapshotter.activity_index if @snapshotter.respond_to?(:activity_index)),
199
198
  range_start: @range.begin_time,
200
199
  range_end: range_end || root_versions.last
@@ -40,8 +40,7 @@ module PaperTrailDiff
40
40
 
41
41
  #: (untyped) -> untyped
42
42
  def trailing_scope(relation)
43
- column = relation.klass.arel_table[:created_at]
44
- relation.where(after_end(column))
43
+ relation.where(after_end(relation.arel_table[:created_at]))
45
44
  end
46
45
 
47
46
  # Each item's earliest version after the range, keyed by item id. One row
@@ -49,12 +48,11 @@ module PaperTrailDiff
49
48
  # the query stays portable; a timestamp tie keeps the lower id.
50
49
  #: (untyped) -> Hash[String, untyped]
51
50
  def first_trailing_versions(relation)
52
- table = relation.klass.arel_table
51
+ table = relation.arel_table
53
52
  first_after = VersionQuery.no_earlier_version(table) do |earlier|
54
53
  after_end(earlier[:created_at])
55
54
  end
56
- versions = trailing_scope(relation).where(first_after)
57
- .reorder(created_at: :asc, id: :asc).to_a
55
+ versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
58
56
  first = {} #: Hash[String, untyped]
59
57
  versions.each { |version| first[version.item_id.to_s] ||= version }
60
58
  first
@@ -76,17 +74,15 @@ module PaperTrailDiff
76
74
 
77
75
  #: (untyped, boundary: Symbol) -> Time
78
76
  def coerce_time(value, boundary:)
79
- unless value.respond_to?(:to_time)
80
- raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
81
- end
82
-
83
77
  time_value(value).getutc.freeze
84
- rescue ArgumentError, NoMethodError, TypeError => e
85
- raise InvalidTimeRangeError,
86
- "`within` #{boundary} must be time-like",
87
- cause: e
78
+ rescue ArgumentError, NoMethodError, TypeError
79
+ raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
88
80
  end
89
81
 
82
+ # Active Support 8.0 and older warn, once per process, that `to_time` will
83
+ # change on a zoned time, so read zoned values without it. Every branch
84
+ # gives the same instant, so no spec (and no mutation) can tell them apart.
85
+ # mutant:disable
90
86
  #: (untyped) -> Time
91
87
  def time_value(value)
92
88
  return value if value.is_a?(Time)
@@ -4,18 +4,18 @@
4
4
  module PaperTrailDiff
5
5
  # Selects in-range root versions plus one later reconstruction boundary.
6
6
  class TimeVersionRange
7
- #: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
8
- def initialize(record, time_range:, version_scope: nil, live_endpoint: nil)
7
+ #: (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
8
+ def initialize(record, time_range:, version_scope:, live_endpoint:)
9
9
  @record = record
10
10
  @time_range = time_range
11
11
  @version_scope = version_scope
12
12
  @live_endpoint = live_endpoint
13
13
  end
14
14
 
15
- #: (?context_required: bool) -> RootVersionPlan
16
- def select_plan(context_required: false)
15
+ #: (context_required: bool) -> RootVersionPlan
16
+ def select_plan(context_required:)
17
17
  relation = Endpoint.versions(@record)
18
- in_range = ordered(@time_range.scope(relation).to_a)
18
+ in_range = ordered(@time_range.scope(relation))
19
19
  RootVersionSelection.new(
20
20
  in_range: in_range,
21
21
  selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
@@ -37,7 +37,7 @@ module PaperTrailDiff
37
37
 
38
38
  #: (untyped) -> untyped
39
39
  def trailing_version(relation)
40
- @time_range.trailing_scope(relation).reorder(created_at: :asc, id: :asc).first
40
+ VersionQuery.chronological(@time_range.trailing_scope(relation)).first
41
41
  end
42
42
 
43
43
  #: (Array[untyped]) -> Array[untyped]
@@ -30,10 +30,11 @@ module PaperTrailDiff
30
30
  end
31
31
 
32
32
  # A record with no versions has no first boundary to resolve, which
33
- # is an empty history rather than a bad request.
33
+ # is an empty history rather than a bad request. Both endpoints are
34
+ # required, so only `:first` can resolve to nothing; a window has none.
34
35
  #: () -> bool
35
36
  def unresolved?
36
- (symbolic?(@requested_from) && @from.nil?) || (symbolic?(@requested_to) && @to.nil?)
37
+ !time? && (@from.nil? || @to.nil?)
37
38
  end
38
39
 
39
40
  # A batch may have selected these versions already, in which case reselecting
@@ -97,7 +98,7 @@ module PaperTrailDiff
97
98
 
98
99
  #: (untyped) -> bool
99
100
  def symbolic?(boundary)
100
- boundary.is_a?(Symbol)
101
+ boundary.instance_of?(Symbol)
101
102
  end
102
103
 
103
104
  # Resolving `:first` here keeps callers from depending on the
@@ -118,7 +119,7 @@ module PaperTrailDiff
118
119
 
119
120
  #: () -> untyped
120
121
  def ordered_versions
121
- Endpoint.versions(@record).reorder(created_at: :asc, id: :asc)
122
+ VersionQuery.chronological(Endpoint.versions(@record))
122
123
  end
123
124
 
124
125
  #: (untyped) -> TimeRange?
@@ -2,5 +2,5 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- VERSION = '0.13.0'
5
+ VERSION = '0.14.0'
6
6
  end