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
@@ -4,12 +4,16 @@
4
4
  module PaperTrailDiff
5
5
  # Validates and executes independent comparisons with shared live endpoint loading.
6
6
  class ComparisonBatch
7
- #: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
7
+ # `history_preparer` prepares roots that have a live endpoint to collect a
8
+ # graph from; `version_history_preparer` prepares roots compared only
9
+ # between versions.
10
+ #: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, version_history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
8
11
  def initialize( # rubocop:disable Metrics/ParameterLists
9
12
  comparisons,
10
13
  live_loader:,
11
14
  preparer:,
12
15
  history_preparer:,
16
+ version_history_preparer:,
13
17
  historical_snapshotter:,
14
18
  live_normalizer:
15
19
  )
@@ -17,6 +21,7 @@ module PaperTrailDiff
17
21
  @live_loader = live_loader
18
22
  @preparer = preparer
19
23
  @history_preparer = history_preparer
24
+ @version_history_preparer = version_history_preparer
20
25
  @historical_snapshotter = historical_snapshotter
21
26
  @live_normalizer = live_normalizer
22
27
  end
@@ -35,6 +40,7 @@ module PaperTrailDiff
35
40
  # @rbs @live_loader: untyped
36
41
  # @rbs @preparer: untyped
37
42
  # @rbs @history_preparer: untyped
43
+ # @rbs @version_history_preparer: untyped
38
44
  # @rbs @historical_snapshotter: untyped
39
45
  # @rbs @live_normalizer: untyped
40
46
 
@@ -97,20 +103,41 @@ module PaperTrailDiff
97
103
 
98
104
  #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
99
105
  def prepare_historical_batches!(pairs, live_records)
100
- grouped = historical_versions(pairs, live_records).group_by do |version|
101
- Endpoint.model_class(version)
106
+ loaded, unloaded = historical_versions(pairs).partition do |version|
107
+ live_records.key?(Endpoint.identity(version))
102
108
  end
103
- grouped.each_value do |versions|
109
+ loaded.group_by { |version| RecordedClass.for(version) }.each_value do |versions|
104
110
  records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }.uniq
105
111
  @history_preparer.call(records, versions)
106
112
  end
113
+ prepare_version_roots!(unloaded)
114
+ end
115
+
116
+ # A root compared only between versions has no live endpoint, and its row
117
+ # may be gone. Without prepared history, PT-AT finds a has_many's children
118
+ # by the keys each version recorded after its change, so it misses a child
119
+ # that later moved to another owner. Such roots are prepared from identity
120
+ # alone, like deleted ones. Their history still reads the live rows it
121
+ # needs: a record's current row is its state after its last version.
122
+ #: (Array[untyped]) -> void
123
+ 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)
126
+ @version_history_preparer.call(ids.map { |id| historical_root(model, id) }, group)
127
+ end
107
128
  end
108
129
 
109
- #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> Array[untyped]
110
- def historical_versions(pairs, live_records)
111
- selected = pairs.flatten.select do |endpoint|
112
- Endpoint.version?(endpoint) && live_records.key?(Endpoint.identity(endpoint))
113
- end
130
+ # The record supplies identity and model metadata only.
131
+ #: (untyped, untyped) -> untyped
132
+ def historical_root(model, id)
133
+ record = model.new
134
+ record[model.primary_key] = id
135
+ record
136
+ end
137
+
138
+ #: (Array[[untyped, untyped]]) -> Array[untyped]
139
+ def historical_versions(pairs)
140
+ selected = pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }
114
141
  selected.uniq { |version| [version.class.name, version.id] }
115
142
  end
116
143
 
@@ -167,7 +194,7 @@ module PaperTrailDiff
167
194
  requirements = {} #: Hash[untyped, bool]
168
195
  pairs.flatten.each_with_object(requirements) do |endpoint, collected|
169
196
  historical = Endpoint.version?(endpoint)
170
- model_class = historical ? Endpoint.model_class(endpoint) : endpoint.class
197
+ model_class = historical ? RecordedClass.for(endpoint) : endpoint.class
171
198
  collected[model_class] = collected.fetch(model_class, false) || historical
172
199
  end
173
200
  end
@@ -4,11 +4,15 @@
4
4
  module PaperTrailDiff
5
5
  # Analyzes missing roots together without pretending that they have live rows.
6
6
  class DeletedAnalysisBatch
7
- #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
7
+ # `context_required` reads a root that did not change in the window from
8
+ # the version after it, so its associations' activity can be reported.
9
+ #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
8
10
  def initialize( # rubocop:disable Metrics/ParameterLists
9
- model, identities:, time_range:, analyzer:, history_preparer:, version_scope: nil
11
+ model, identities:, time_range:, analyzer:, history_preparer:, version_scope:,
12
+ context_required:
10
13
  )
11
14
  @model = model
15
+ @context_required = context_required
12
16
  @identities = identities
13
17
  @time_range = time_range
14
18
  @analyzer = analyzer
@@ -18,13 +22,9 @@ module PaperTrailDiff
18
22
 
19
23
  #: () -> Hash[Array[String], Analysis?]
20
24
  def call
21
- empty = {} #: Hash[Array[String], Analysis?]
22
- return empty.freeze if @identities.empty?
23
-
24
- records = historical_roots
25
- selected = BatchedRootVersions.new(
26
- records, time_range: @time_range, version_scope: @version_scope
27
- ).call
25
+ destroys = destroy_versions
26
+ records = historical_roots(destroys)
27
+ selected = plans(records, destroys)
28
28
  prepare(records, selected)
29
29
  analyses = records.to_h do |record|
30
30
  key = Endpoint.identity(record)
@@ -42,19 +42,39 @@ module PaperTrailDiff
42
42
  end
43
43
 
44
44
  # @rbs @model: untyped
45
+ # @rbs @context_required: bool
45
46
  # @rbs @identities: Array[Array[String]]
46
47
  # @rbs @time_range: TimeRange?
47
48
  # @rbs @analyzer: untyped
48
49
  # @rbs @history_preparer: untyped
49
50
  # @rbs @version_scope: untyped
50
51
 
52
+ # A root destroyed before the window had no state inside it to read, so
53
+ # only the others take the version after the window as context.
54
+ #: (Array[untyped], Array[untyped]) -> Hash[Array[String], RootVersionPlan]
55
+ def plans(records, destroys)
56
+ start = @time_range&.begin_time
57
+ early = destroys.select { |version| start && version.created_at < start }
58
+ .map { |version| version.item_id.to_s }
59
+ before, during = records.partition { |record| early.include?(record.id.to_s) }
60
+ plans_for(during, @context_required).merge(plans_for(before, false))
61
+ end
62
+
63
+ #: (Array[untyped], bool) -> Hash[Array[String], RootVersionPlan]
64
+ def plans_for(records, context_required)
65
+ BatchedRootVersions.new(
66
+ records, time_range: @time_range, version_scope: @version_scope,
67
+ live_endpoints: nil, context_required: context_required
68
+ ).call
69
+ end
70
+
51
71
  # These records supply identity and model metadata only. Every reported
52
72
  # value comes from the batched historical plan; no per-root reify or live
53
73
  # lookup is needed to get into the comparison engine.
54
- #: () -> Array[untyped]
55
- def historical_roots
74
+ #: (Array[untyped]) -> Array[untyped]
75
+ def historical_roots(destroys)
56
76
  loader = PreparedVersionStateLoader.new
57
- destroy_versions.map do |version|
77
+ destroys.map do |version|
58
78
  model = loader.call(version)&.model_class || Endpoint.model_class(version)
59
79
  record = model.new
60
80
  record[model.primary_key] = version.item_id
@@ -64,12 +84,11 @@ module PaperTrailDiff
64
84
 
65
85
  #: () -> Array[untyped]
66
86
  def destroy_versions
67
- versions = @model.paper_trail.version_class.where(
87
+ destroys = @model.paper_trail.version_class.where(
68
88
  item_type: @model.base_class.name, item_id: @identities.map(&:last), event: 'destroy'
69
- ).reorder(created_at: :asc, id: :asc)
70
- versions.group_by { |version| version.item_id.to_s }.values.map do |history|
71
- Support.chronological_sort(history).last
72
- end
89
+ )
90
+ # Oldest first, so each item keeps its latest destroy.
91
+ VersionQuery.chronological(destroys).index_by(&:item_id).values
73
92
  end
74
93
 
75
94
  #: (Array[untyped]) -> Hash[Symbol, untyped]
@@ -91,7 +91,7 @@ module PaperTrailDiff
91
91
  selected = traversal.selected_reflections(model_class)
92
92
  inspect_targets(selected)
93
93
  inspect_checkpoint_timestamp(model_class)
94
- inspect_habtm(selected)
94
+ inspect_habtm(model_class, selected)
95
95
  DiagnosticReport.new(issues: @issues)
96
96
  end
97
97
 
@@ -126,14 +126,32 @@ module PaperTrailDiff
126
126
  end
127
127
  end
128
128
 
129
- #: (Array[Array[untyped]]) -> void
130
- def inspect_habtm(selected)
131
- paths = selected.filter_map do |path, reflection|
132
- path if reflection.macro == :has_and_belongs_to_many
133
- end
134
- return if paths.empty?
129
+ #: (untyped, Array[Array[untyped]]) -> void
130
+ def inspect_habtm(model_class, selected)
131
+ habtm = selected.select { |_, reflection| reflection.macro == :has_and_belongs_to_many }
132
+ return if habtm.empty?
133
+
134
+ inspect_transaction_metadata(habtm.map(&:first))
135
+ inspect_shared_transactions(model_class, habtm)
136
+ end
135
137
 
136
- inspect_transaction_metadata(paths)
138
+ # PT-AT does not record which owner a HABTM member belongs to, so a
139
+ # transaction that more than one owner recorded members in cannot be read.
140
+ #: (untyped, Array[Array[untyped]]) -> void
141
+ def inspect_shared_transactions(model_class, habtm)
142
+ versions = [@from_version, @to_version].select do |version|
143
+ version.respond_to?(:transaction_id) && version.transaction_id
144
+ end
145
+ habtm.each do |path, reflection|
146
+ owners = HabtmTransactionOwners.new(model_class, reflection)
147
+ versions.each do |version|
148
+ next unless owners.ambiguous?(version.transaction_id)
149
+
150
+ add_error(:habtm_transaction_shared,
151
+ 'HABTM endpoint shares its transaction with another owner of the association',
152
+ path, version.id)
153
+ end
154
+ end
137
155
  end
138
156
 
139
157
  #: () -> void
@@ -45,13 +45,22 @@ module PaperTrailDiff
45
45
 
46
46
  #: (untyped) -> bool
47
47
  def plain_model?(model)
48
- !model.primary_key.is_a?(Array) && !model.default_scopes? &&
48
+ !model.primary_key.is_a?(Array) && !scope_assigns_attributes?(model) &&
49
49
  model._initialize_callbacks.empty? &&
50
50
  %i[initialize attributes []= write_attribute id].all? do |name|
51
51
  framework_class?(model.instance_method(name).owner)
52
52
  end
53
53
  end
54
54
 
55
+ # A default scope's equality conditions are assigned to every new record,
56
+ # through the model's writers, before a reified version's attributes are.
57
+ # A subclass's own type is assigned with or without one.
58
+ #: (untyped) -> bool
59
+ def scope_assigns_attributes?(model)
60
+ model.default_scopes? &&
61
+ model.default_scoped.scope_for_create != model.unscoped.scope_for_create
62
+ end
63
+
55
64
  #: (untyped) -> bool
56
65
  def plain_attributes?(model)
57
66
  return false if encrypted?(model)
@@ -58,7 +58,8 @@ module PaperTrailDiff
58
58
  # Raised when association comparison is requested without an available PT-AT setup.
59
59
  class AssociationTrackingUnavailableError < Error; end
60
60
 
61
- # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association.
61
+ # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association,
62
+ # or a polymorphic type names no class.
62
63
  class IncompleteAssociationHistoryError < Error; end
63
64
 
64
65
  # Raised when current-ended activity cannot be reconstructed for a selected association.
@@ -0,0 +1,68 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # PT-AT records HABTM members under a transaction id and the association's
6
+ # name, with nothing naming the record they belong to. When more than one
7
+ # record that can own that name saved a version in the transaction, their
8
+ # members are mixed together and none of them can be read back.
9
+ class HabtmTransactionOwners
10
+ #: (untyped, untyped) -> void
11
+ def initialize(owner_class, reflection)
12
+ @versions = owner_class.paper_trail.version_class
13
+ @associations = owner_class.paper_trail.version_association_class
14
+ @name = reflection.name.to_s
15
+ @owner_types = {} #: Hash[String, bool]
16
+ end
17
+
18
+ # The given transactions (one id or several) in which more than one
19
+ # possible owner saved a version, as strings.
20
+ #: (untyped) -> Array[String]
21
+ def shared(transaction_ids)
22
+ items = @versions.where(transaction_id: transaction_ids).distinct
23
+ .pluck(:transaction_id, :item_type, :item_id)
24
+ owners = items.select { |_, type, _| owner_type?(type) }
25
+ owners.group_by { |transaction_id, _, _| transaction_id.to_s }
26
+ .filter_map { |transaction_id, rows| transaction_id if rows.size > 1 }
27
+ end
28
+
29
+ # Members recorded in a shared transaction cannot be told apart. With no
30
+ # members recorded, every owner had none, so that reads correctly.
31
+ #: (untyped) -> bool
32
+ def ambiguous?(transaction_id)
33
+ shared(transaction_id).any? &&
34
+ @associations.exists?(version_id: transaction_id, foreign_key_name: @name)
35
+ end
36
+
37
+ #: (untyped) -> void
38
+ def ensure_single_owner!(transaction_id)
39
+ return unless ambiguous?(transaction_id)
40
+
41
+ message = "HABTM history is ambiguous for #{@name} at transaction #{transaction_id}: " \
42
+ "more than one record with a #{@name} association saved a version in it, " \
43
+ 'and PT-AT does not record which members belong to which record'
44
+ raise IncompleteAssociationHistoryError, message
45
+ end
46
+
47
+ private
48
+
49
+ # @rbs @versions: untyped
50
+ # @rbs @associations: untyped
51
+ # @rbs @name: String
52
+ # @rbs @owner_types: Hash[String, bool]
53
+
54
+ # Versions name the base class, so a HABTM declared on a subclass counts.
55
+ # A type that names no model may have recorded members when it existed.
56
+ #: (String) -> bool
57
+ def owner_type?(type)
58
+ @owner_types.fetch(type) do
59
+ model_class = AssociationTraversal.named_class(type)
60
+ @owner_types[type] =
61
+ !model_class.respond_to?(:reflect_on_association) ||
62
+ [model_class, *model_class.descendants].any? do |candidate|
63
+ candidate.reflect_on_association(@name)&.macro == :has_and_belongs_to_many
64
+ end
65
+ end
66
+ end
67
+ end
68
+ end
@@ -37,7 +37,7 @@ module PaperTrailDiff
37
37
  reified[reflection.name] = true
38
38
  case reflection.macro
39
39
  when :belongs_to
40
- reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
40
+ reify_belongs_to(record, reflection)
41
41
  when :has_one
42
42
  reifier(:HasOne).reify(reflection, record, options, @transaction_id)
43
43
  when :has_many
@@ -47,6 +47,26 @@ module PaperTrailDiff
47
47
  end
48
48
  end
49
49
 
50
+ #: (untyped, untyped) -> void
51
+ def reify_belongs_to(record, reflection)
52
+ ensure_versioned_target!(record, reflection) if reflection.polymorphic?
53
+ reifier(:BelongsTo).reify(reflection, record, options, @transaction_id)
54
+ end
55
+
56
+ # A polymorphic target's class is known only from the record's type
57
+ # column, so TraversalPreparer cannot check it is versioned up front.
58
+ #: (untyped, untyped) -> void
59
+ def ensure_versioned_target!(record, reflection)
60
+ model_class = AssociationTraversal.belongs_to_target(reflection, record)
61
+ return if model_class.nil? || Support.versioned?(model_class)
62
+
63
+ raise UnversionedAssociationError,
64
+ "association #{record.class.name}##{reflection.name} cannot be compared " \
65
+ "historically: it points at #{model_class.name}, which is not versioned. Add " \
66
+ "`has_paper_trail` to #{model_class.name}, or mirror the fields you need onto a " \
67
+ 'model that has it.'
68
+ end
69
+
50
70
  #: (untyped, untyped) -> void
51
71
  def reify_has_many(record, reflection)
52
72
  if reflection.options[:through]
@@ -70,7 +90,7 @@ module PaperTrailDiff
70
90
  #: (untyped, untyped) -> void
71
91
  def reify_through(record, reflection)
72
92
  source = reflection.source_reflection
73
- if source.belongs_to?
93
+ if pt_at_source?(reflection)
74
94
  reifier(:HasManyThrough).reify(reflection, record, options, @transaction_id)
75
95
  return
76
96
  end
@@ -81,9 +101,17 @@ module PaperTrailDiff
81
101
  association.loaded!
82
102
  end
83
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
+
84
111
  #: (untyped, untyped, untyped) -> Array[untyped]
85
112
  def through_members(record, reflection, source)
86
113
  joins = Array(record.public_send(reflection.through_reflection.name)) #: Array[untyped]
114
+ joins = joins.select { |join| AssociationTraversal.source_type_join?(reflection, join) }
87
115
  joins.flat_map do |join|
88
116
  reify_association(join, source)
89
117
  Array(join.public_send(source.name))
@@ -96,6 +124,8 @@ module PaperTrailDiff
96
124
  message = 'HABTM reconstruction requires a transaction-backed endpoint version'
97
125
  raise IncompleteAssociationHistoryError, message
98
126
  end
127
+ HabtmTransactionOwners.new(record.class, reflection)
128
+ .ensure_single_owner!(@habtm_transaction_id)
99
129
 
100
130
  paper_trail = Object.const_get(:PaperTrail) #: untyped
101
131
  target_versioned = paper_trail.request.enabled_for_model?(reflection.klass)
@@ -69,7 +69,7 @@ module PaperTrailDiff
69
69
 
70
70
  #: (untyped) -> Integer
71
71
  def validate_budget(value)
72
- return value if value.is_a?(Integer) && value.positive?
72
+ return value if value.instance_of?(Integer) && value.positive?
73
73
 
74
74
  raise ConfigurationError, 'max_filter_versions: must be a positive Integer'
75
75
  end
@@ -80,13 +80,13 @@ module PaperTrailDiff
80
80
  item_id: ids)
81
81
  range = @time_range
82
82
  relation = range.scope(relation) if range
83
- versions = relation.reorder(created_at: :asc, id: :asc)
84
- .limit(@max_versions - @loaded + 1).to_a
83
+ # One past the remaining budget is enough to know it was exceeded.
84
+ versions = VersionQuery.chronological(relation).limit(@max_versions - @loaded + 1)
85
85
  account_versions!(versions.length)
86
86
  versions.group_by { |version| version.item_id.to_s }
87
87
  end
88
88
 
89
- #: (Array[untyped], untyped) -> bool
89
+ #: (Array[untyped], untyped) -> boolish
90
90
  def held?(versions, closing)
91
91
  return true if versions.any? { |version| matches?(version) }
92
92
  return false unless closing
@@ -97,9 +97,7 @@ module PaperTrailDiff
97
97
  # What each candidate held after its last change in the window.
98
98
  #: (Array[String], Hash[String, Array[untyped]]) -> Hash[String, untyped]
99
99
  def closing_states(ids, versions)
100
- open = ids.reject { |id| versions.fetch(id, []).last&.event.to_s == 'destroy' }
101
- return {} if open.empty?
102
-
100
+ open = ids.reject { |id| versions.fetch(id, []).last&.event == 'destroy' }
103
101
  trailing = trailing_versions(open)
104
102
  trailing.merge(live_records(open - trailing.keys))
105
103
  end
@@ -118,15 +116,12 @@ module PaperTrailDiff
118
116
 
119
117
  #: (Array[String]) -> Hash[String, untyped]
120
118
  def live_records(ids)
121
- return {} if ids.empty?
122
-
123
- @model.base_class.unscoped.where(@model.primary_key => ids).to_a
124
- .to_h { |record| [record.id.to_s, record] }
119
+ @model.unscoped.where(@model.primary_key => ids).to_h { |record| [record.id.to_s, record] }
125
120
  end
126
121
 
127
- #: (untyped) -> bool
122
+ #: (untyped) -> boolish
128
123
  def record_matches?(record)
129
- return !!@predicate.call(record) unless @predicate.is_a?(Hash)
124
+ return @predicate.call(record) unless @predicate.instance_of?(Hash)
130
125
 
131
126
  @predicate.all? { |name, expected| record.attributes.fetch(name) == expected }
132
127
  end
@@ -141,16 +136,16 @@ module PaperTrailDiff
141
136
  'narrow the window or explicitly increase the version budget'
142
137
  end
143
138
 
144
- #: (untyped) -> bool
139
+ #: (untyped) -> boolish
145
140
  def matches?(version)
146
- if @predicate.is_a?(Hash)
141
+ if @predicate.instance_of?(Hash)
147
142
  return false unless version.object
148
143
 
149
144
  return attributes_match?(version)
150
145
  end
151
146
 
152
147
  state = version.reify(dup: true)
153
- !!(state && @predicate.call(state))
148
+ state && @predicate.call(state)
154
149
  end
155
150
 
156
151
  #: (untyped) -> bool
@@ -167,7 +162,7 @@ module PaperTrailDiff
167
162
  "historical_filter: #{name} was not recorded in version #{version.id}"
168
163
  end
169
164
 
170
- state.model_class.type_for_attribute(name).cast(state.attributes.fetch(name)) == expected
165
+ state.attributes.fetch(name) == expected
171
166
  end
172
167
  end
173
168
 
@@ -34,12 +34,8 @@ module PaperTrailDiff
34
34
  end
35
35
 
36
36
  @prepared_history = PreparedHistoryLoader.new(
37
- record,
38
- root_versions: root_versions,
39
- start_at: start_at,
40
- end_at: end_at,
41
- tree: @tree,
42
- traversal: @traversal
37
+ record, root_ids: [record.id], root_versions: root_versions, start_at: start_at,
38
+ end_at: end_at, tree: @tree, traversal: @traversal, live_records: []
43
39
  ).call
44
40
  end
45
41
 
@@ -52,8 +48,9 @@ module PaperTrailDiff
52
48
  end
53
49
  end
54
50
 
55
- # Missing roots have no live graph to collect. Reading their associations
56
- # here would issue a query per root and seed nonexistent rows as live state.
51
+ # Missing roots, and roots compared only between versions, have no live
52
+ # graph to collect. Reading their associations here would issue a query
53
+ # per root and seed nonexistent rows as live state.
57
54
  #: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
58
55
  def prepare_deleted_batch(records, root_versions, start_at: nil, end_at: nil)
59
56
  return if @tree.empty? || records.empty? || root_versions.empty?
@@ -175,7 +172,7 @@ module PaperTrailDiff
175
172
 
176
173
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
177
174
  def snapshot_from_version(root_version, context_version, tree:, normalizer:)
178
- model_class = Endpoint.model_class(root_version)
175
+ model_class = RecordedClass.for(root_version)
179
176
  @preparer.call(model_class, historical: true)
180
177
  @traversal.ensure_habtm_history!(model_class, root_version)
181
178
  handled, snapshot = @prepared_snapshotter.call(
@@ -44,7 +44,9 @@ module PaperTrailDiff
44
44
 
45
45
  #: (untyped, Array[untyped], AssociationTree) -> void
46
46
  def preload_model_tree(model_class, records, tree)
47
- batch, individual = selected_reflections(model_class, tree).partition do |reflection, _|
47
+ reflections = selected_reflections(model_class, tree)
48
+ resolve_polymorphic_targets(records, reflections)
49
+ batch, individual = reflections.partition do |reflection, _|
48
50
  batch_safe?(records.fetch(0), reflection)
49
51
  end
50
52
  preload_batch(records, batch.map { |reflection, _| reflection.name })
@@ -62,6 +64,15 @@ module PaperTrailDiff
62
64
  end
63
65
  end
64
66
 
67
+ # Active Record raises a bare NameError for a type that names no class, so
68
+ # each type is resolved first to raise one that names the record.
69
+ #: (Array[untyped], Array[[untyped, AssociationTree]]) -> void
70
+ def resolve_polymorphic_targets(records, reflections)
71
+ reflections.map(&:first).select(&:polymorphic?).each do |reflection|
72
+ records.each { |record| AssociationTraversal.belongs_to_target(reflection, record) }
73
+ end
74
+ end
75
+
65
76
  #: (Array[untyped], Array[[untyped, AssociationTree]], individually: bool) -> void
66
77
  def preload_subtrees(records, reflections, individually:)
67
78
  reflections.each do |reflection, subtree|
@@ -90,16 +101,38 @@ module PaperTrailDiff
90
101
  active_record.const_get(:Associations).const_get(:Preloader)
91
102
  end
92
103
 
104
+ # The preloader applies a limit or offset to all owners' records at once,
105
+ # not to each owner's, so such an association is loaded per record. A
106
+ # has_one is no exception. Through a part with a limit, an offset or a
107
+ # has_one cut, the preloader keeps what the part alone would load, while
108
+ # the through's own query keeps the part's conditions only.
93
109
  #: (untyped, untyped) -> bool
94
110
  def batch_safe?(record, reflection)
95
111
  scope = reflection.scope
96
112
  return false if scope && !scope.arity.zero?
97
- return true unless reflection.collection?
113
+ return true unless reflection.collection? || reflection.has_one?
114
+ return false if cut_part?(reflection)
98
115
 
99
116
  relation = record.association(reflection.name).scope
100
117
  relation.limit_value.nil? && relation.offset_value.nil?
101
118
  end
102
119
 
120
+ #: (untyped) -> bool
121
+ def cut_part?(reflection)
122
+ reflection.collection? &&
123
+ (ScopeCondition.ranked_parts?(reflection) || through_parts(reflection).any?(&:has_one?))
124
+ end
125
+
126
+ # Every part a through passes, at any depth.
127
+ #: (untyped) -> Array[untyped]
128
+ def through_parts(reflection)
129
+ return [] unless reflection.through_reflection?
130
+
131
+ [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
132
+ [part, *through_parts(part)]
133
+ end
134
+ end
135
+
103
136
  #: (Array[untyped], untyped) -> Array[untyped]
104
137
  def load_individually(records, reflection)
105
138
  unique_records(records.flat_map do |record|
@@ -36,7 +36,7 @@ module PaperTrailDiff
36
36
  subtree = tree.child(reflection.name)
37
37
  next unless subtree
38
38
 
39
- child_path = Support.association_path(path, reflection.name.to_s)
39
+ child_path = Support.association_path(path, reflection.name)
40
40
  collect(children_for(records, reflection), subtree, path: child_path, into: into)
41
41
  end
42
42
  end