paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -3,8 +3,10 @@
3
3
  module PaperTrailDiff
4
4
  # Analyzes missing roots together without pretending that they have live rows.
5
5
  class DeletedAnalysisBatch
6
- # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
7
- def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
6
+ # `context_required` reads a root that did not change in the window from
7
+ # the version after it, so its associations' activity can be reported.
8
+ # : (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
9
+ def initialize: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
8
10
 
9
11
  # : () -> Hash[Array[String], Analysis?]
10
12
  def call: () -> Hash[Array[String], Analysis?]
@@ -16,6 +18,8 @@ module PaperTrailDiff
16
18
 
17
19
  @analyzer: untyped
18
20
 
21
+ @context_required: bool
22
+
19
23
  @history_preparer: untyped
20
24
 
21
25
  @identities: Array[Array[String]]
@@ -26,19 +30,27 @@ module PaperTrailDiff
26
30
 
27
31
  @version_scope: untyped
28
32
 
33
+ # A root destroyed before the window had no state inside it to read, so
34
+ # only the others take the version after the window as context.
35
+ # : (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
36
+ def plans: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
37
+
38
+ # : (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
39
+ def plans_for: (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
40
+
29
41
  # These records supply identity and model metadata only. Every reported
30
42
  # value comes from the batched historical plan; no per-root reify or live
31
43
  # lookup is needed to get into the comparison engine.
32
- # : () -> Array[untyped]
33
- def historical_roots: () -> Array[untyped]
44
+ # : (Array[untyped]) -> Array[untyped]
45
+ def historical_roots: (Array[untyped]) -> Array[untyped]
34
46
 
35
47
  # : () -> Array[untyped]
36
48
  def destroy_versions: () -> Array[untyped]
37
49
 
38
- # : (Array[untyped]) -> Hash[Symbol, untyped]
39
- def preparation_range: (Array[untyped]) -> Hash[Symbol, untyped]
50
+ # : (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
51
+ def preparation_range: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
40
52
 
41
- # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
42
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
53
+ # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
54
+ def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
43
55
  end
44
56
  end
@@ -0,0 +1,48 @@
1
+ # Generated from lib/paper_trail_diff/deleted_root_filter.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Keeps the deleted roots the relation would have selected, by the state
5
+ # each held when it was destroyed. A relation's conditions read the live
6
+ # table, where a destroyed root has no row, so without this a report on one
7
+ # account's records would include every account's deletions.
8
+ class DeletedRootFilter
9
+ # : (untyped) -> void
10
+ def initialize: (untyped) -> void
11
+
12
+ # A root whose destroy PaperTrail did not record has no state to test
13
+ # and stays, as it has no state to report either. One whose destroy
14
+ # recorded no state is left out.
15
+ # : (Array[Array[String]]) -> Array[Array[String]]
16
+ def call: (Array[Array[String]]) -> Array[Array[String]]
17
+
18
+ private
19
+
20
+ @condition: ScopeCondition
21
+
22
+ @loader: DirectRecordStateLoader
23
+
24
+ @relation: untyped
25
+
26
+ # A relation delegates class methods to its model, so every mutation here,
27
+ # which drops `.model`, answers the same.
28
+ # mutant:disable
29
+ # : () -> untyped
30
+ def model: () -> untyped
31
+
32
+ # : (Hash[String, untyped]?) -> bool
33
+ def selected?: (Hash[String, untyped]?) -> bool
34
+
35
+ # The state each root held before its latest destroy.
36
+ # : (Array[String]) -> Hash[String, Hash[String, untyped]?]
37
+ def destroyed_states: (Array[String]) -> Hash[String, Hash[String, untyped]?]
38
+
39
+ # Read directly, with a column `skip:` left out of history as its default,
40
+ # so a report checks its ceiling before reifying anything. A version the
41
+ # direct reader declines, such as one naming a column since removed, is
42
+ # reified. Only the record's own attributes are read, so the association
43
+ # options, which only spare queries, cannot change an answer.
44
+ # mutant:disable
45
+ # : (untyped) -> Hash[String, untyped]?
46
+ def reified_attributes: (untyped) -> Hash[String, untyped]?
47
+ end
48
+ end
@@ -0,0 +1,35 @@
1
+ # Generated from lib/paper_trail_diff/deprecation.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Warns about options that do nothing any more and will be removed. In a
5
+ # Rails app, register the deprecator to configure it with the app's own:
6
+ #
7
+ # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
8
+ module Deprecation
9
+ CLOSE_ON: ::String
10
+
11
+ ALLOW_EXPENSIVE: ::String
12
+
13
+ RELOAD_LIVE_ENDPOINTS: ::String
14
+
15
+ # Required when first used, as the library loads nothing it does not need.
16
+ # : () -> untyped
17
+ def self.deprecator: () -> untyped
18
+
19
+ # The one value close_on: took. It named what ends a wall-clock window,
20
+ # so it was meaningless without one, and until it is removed it is still
21
+ # checked as it was.
22
+ CLOSE_ON_CURRENT: ::Symbol
23
+
24
+ # : (Symbol?, untyped) -> void
25
+ def self.close_on!: (Symbol?, untyped) -> void
26
+
27
+ # : (untyped) -> void
28
+ def self.allow_expensive!: (untyped) -> void
29
+
30
+ # The value to use: the option still works until it is removed, and nil
31
+ # stands for its old default.
32
+ # : (untyped) -> untyped
33
+ def self.reload_live_endpoints!: (untyped) -> untyped
34
+ end
35
+ end
@@ -41,64 +41,76 @@ module PaperTrailDiff
41
41
  end
42
42
 
43
43
  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
44
+ #
45
+ # The endpoints are a comparison's: two versions, or a version and the
46
+ # current record, in either order. Two current records read no history, so
47
+ # nothing is checked.
44
48
  class HistoryDiagnostics
45
- # : (untyped, untyped, associations: Array[String | Symbol]) -> void
46
- def initialize: (untyped, untyped, associations: Array[String | Symbol]) -> void
49
+ STOPPING_CODES: untyped
50
+
51
+ # : (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
52
+ def initialize: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
47
53
 
48
54
  # : () -> DiagnosticReport
49
55
  def call: () -> DiagnosticReport
50
56
 
51
57
  private
52
58
 
53
- @from_version: untyped
59
+ # Each refusal a comparison would raise is an error, so `ok?` is false
60
+ # exactly when one would. The checks after them read reflections that must
61
+ # resolve and PT-AT records that must be there.
62
+ # : (untyped) -> void
63
+ def inspect_associations: (untyped) -> void
64
+
65
+ @allow_approximate: bool
54
66
 
55
67
  @issues: Array[DiagnosticIssue]
56
68
 
57
- @to_version: untyped
69
+ @preparer: TraversalPreparer
70
+
71
+ @traversal: AssociationTraversal
58
72
 
59
73
  @tree: AssociationTree
60
74
 
61
- # : () -> untyped
62
- def validated_model_class: () -> untyped
75
+ @versions: Array[untyped]
63
76
 
64
- # : (Array[Array[untyped]]) -> void
65
- def inspect_targets: (Array[Array[untyped]]) -> void
77
+ # The endpoints that are versions, in the order given.
78
+ # : (untyped, untyped) -> Array[untyped]
79
+ def validated_versions: (untyped, untyped) -> Array[untyped]
66
80
 
67
81
  # : (Array[Array[untyped]]) -> void
68
- def inspect_habtm: (Array[Array[untyped]]) -> void
69
-
70
- # : () -> void
71
- def inspect_version_sequence: () -> void
82
+ def inspect_polymorphic_targets: (Array[Array[untyped]]) -> void
72
83
 
84
+ # Accepted, but read the way `allow_approximate:` describes.
73
85
  # : (untyped) -> void
74
- def inspect_checkpoint_timestamp: (untyped) -> void
86
+ def inspect_approximate_paths: (untyped) -> void
75
87
 
76
- # : (Array[String]) -> void
77
- def inspect_transaction_metadata: (Array[String]) -> void
88
+ # : (untyped, Array[Array[untyped]]) -> void
89
+ def inspect_habtm: (untyped, Array[Array[untyped]]) -> void
78
90
 
79
- # : (untyped, String) -> void
80
- def inspect_versioned_model: (untyped, String) -> void
91
+ # PT-AT does not record which owner a HABTM member belongs to, so a
92
+ # transaction that more than one owner recorded members in cannot be read.
93
+ # : (untyped, Array[Array[untyped]]) -> void
94
+ def inspect_shared_transactions: (untyped, Array[Array[untyped]]) -> void
81
95
 
82
- # : (untyped, String) -> void
83
- def inspect_through_model: (untyped, String) -> void
84
-
85
- # : (untyped) -> bool
86
- def model_versioned?: (untyped) -> bool
96
+ # With the current record as one endpoint there is one version, and the
97
+ # sequence runs on from it.
98
+ # : (untyped) -> void
99
+ def inspect_version_sequence: (untyped) -> void
87
100
 
101
+ # Only a path PT-AT reads can lose a change between tied versions, and a
102
+ # traversal that does not resolve reads nothing at all.
88
103
  # : (untyped) -> bool
89
- def synchronized_timestamp_disabled?: (untyped) -> bool
104
+ def fallback_selected?: (untyped) -> bool
90
105
 
91
- # : () -> bool
92
- def association_tracking_available?: () -> bool
93
-
94
- # : (untyped) -> Array[String]
95
- def version_identity: (untyped) -> Array[String]
106
+ # : (untyped) -> void
107
+ def inspect_checkpoint_timestamp: (untyped) -> void
96
108
 
97
- # : (untyped) -> String
98
- def version_type: (untyped) -> String
109
+ # : (Array[String]) -> void
110
+ def inspect_transaction_metadata: (Array[String]) -> void
99
111
 
100
- # : () -> String
101
- def tracking_unavailable_message: () -> String
112
+ # : (untyped) -> bool
113
+ def synchronized_timestamp_disabled?: (untyped) -> bool
102
114
 
103
115
  # : (Symbol, String, ?String?, ?untyped) -> void
104
116
  def add_error: (Symbol, String, ?String?, ?untyped) -> void
@@ -27,6 +27,12 @@ module PaperTrailDiff
27
27
  # : (untyped) -> bool
28
28
  def plain_model?: (untyped) -> bool
29
29
 
30
+ # A default scope's equality conditions are assigned to every new record,
31
+ # through the model's writers, before a reified version's attributes are.
32
+ # A subclass's own type is assigned with or without one.
33
+ # : (untyped) -> bool
34
+ def scope_assigns_attributes?: (untyped) -> bool
35
+
30
36
  # : (untyped) -> bool
31
37
  def plain_attributes?: (untyped) -> bool
32
38
 
@@ -21,6 +21,15 @@ module PaperTrailDiff
21
21
  # : (untyped) -> void
22
22
  def self?.validate!: (untyped) -> void
23
23
 
24
+ # The record a method reads the history of: a record, saved or destroyed,
25
+ # of a model PaperTrail versions.
26
+ # : (untyped) -> void
27
+ def self?.validate_root!: (untyped) -> void
28
+
29
+ # A relation is named rather than inspected, which would load it.
30
+ # : (untyped) -> String
31
+ def self?.described: (untyped) -> String
32
+
24
33
  # : (untyped) -> bool
25
34
  def self?.version?: (untyped) -> bool
26
35
 
@@ -33,8 +42,8 @@ module PaperTrailDiff
33
42
  # : (untyped) -> untyped
34
43
  def self?.model_class: (untyped) -> untyped
35
44
 
36
- # The record's own PaperTrail versions, under whatever name the model gave
37
- # the association.
45
+ # Every PaperTrail version of the record, whatever scope its versions
46
+ # association has.
38
47
  # : (untyped) -> untyped
39
48
  def self?.versions: (untyped) -> untyped
40
49
 
@@ -54,7 +54,9 @@ module PaperTrailDiff
54
54
  class FilterLimitExceededError < Error
55
55
  end
56
56
 
57
- # A batch selected a known expensive association without explicitly opting in.
57
+ # No longer raised: `allow_approximate: true` alone accepts the paths it
58
+ # refused. Kept until `allow_expensive:` is removed, so code that rescues it
59
+ # still loads.
58
60
  class UnsupportedBatchPathError < ConfigurationError
59
61
  end
60
62
 
@@ -75,7 +77,8 @@ module PaperTrailDiff
75
77
  class AssociationTrackingUnavailableError < Error
76
78
  end
77
79
 
78
- # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association.
80
+ # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association,
81
+ # or a polymorphic type names no class.
79
82
  class IncompleteAssociationHistoryError < Error
80
83
  end
81
84
 
@@ -0,0 +1,22 @@
1
+ # Generated from lib/paper_trail_diff/fallback_paths.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Whether a request may read a path with PT-AT's reifier rather than from
5
+ # loaded history. PT-AT places association changes by timestamp alone, so
6
+ # only such a path can miss a change between two versions that share one;
7
+ # loaded history orders those versions by id.
8
+ module FallbackPaths
9
+ # A path history reads only approximately counts when it is allowed: a
10
+ # request that does not allow it is refused before anything is read.
11
+ # : (AssociationTraversal, untyped, approximate: bool) -> bool
12
+ def self.any?: (AssociationTraversal, untyped, approximate: bool) -> bool
13
+
14
+ # Loaded history cannot index a composite foreign key, and a polymorphic
15
+ # belongs_to's target, with its default scope, is known only per record.
16
+ # : (untyped) -> bool
17
+ def self.per_record?: (untyped) -> bool
18
+
19
+ # : (untyped) -> bool
20
+ def self.composite_key?: (untyped) -> bool
21
+ end
22
+ end
@@ -0,0 +1,40 @@
1
+ # Generated from lib/paper_trail_diff/habtm_transaction_owners.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # PT-AT records HABTM members under a transaction id and the association's
5
+ # name, with nothing naming the record they belong to. When more than one
6
+ # record that can own that name saved a version in the transaction, their
7
+ # members are mixed together and none of them can be read back.
8
+ class HabtmTransactionOwners
9
+ # : (untyped, untyped) -> void
10
+ def initialize: (untyped, untyped) -> void
11
+
12
+ # The given transactions (one id or several) in which more than one
13
+ # possible owner saved a version, as strings.
14
+ # : (untyped) -> Array[String]
15
+ def shared: (untyped) -> Array[String]
16
+
17
+ # Members recorded in a shared transaction cannot be told apart. With no
18
+ # members recorded, every owner had none, so that reads correctly.
19
+ # : (untyped) -> bool
20
+ def ambiguous?: (untyped) -> bool
21
+
22
+ # : (untyped) -> void
23
+ def ensure_single_owner!: (untyped) -> void
24
+
25
+ private
26
+
27
+ @associations: untyped
28
+
29
+ @name: String
30
+
31
+ @owner_types: Hash[String, bool]
32
+
33
+ @versions: untyped
34
+
35
+ # Versions name the base class, so a HABTM declared on a subclass counts.
36
+ # A type that names no model may have recorded members when it existed.
37
+ # : (String) -> bool
38
+ def owner_type?: (String) -> bool
39
+ end
40
+ end
@@ -22,6 +22,14 @@ module PaperTrailDiff
22
22
  # : (untyped, untyped) -> void
23
23
  def reify_association: (untyped, untyped) -> void
24
24
 
25
+ # : (untyped, untyped) -> void
26
+ def reify_belongs_to: (untyped, untyped) -> void
27
+
28
+ # A polymorphic target's class is known only from the record's type
29
+ # column, so TraversalPreparer cannot check it is versioned up front.
30
+ # : (untyped, untyped) -> void
31
+ def ensure_versioned_target!: (untyped, untyped) -> void
32
+
25
33
  # : (untyped, untyped) -> void
26
34
  def reify_has_many: (untyped, untyped) -> void
27
35
 
@@ -30,6 +38,11 @@ module PaperTrailDiff
30
38
  # : (untyped, untyped) -> void
31
39
  def reify_through: (untyped, untyped) -> void
32
40
 
41
+ # PT-AT's belongs_to source ignores `source_type:` and reads targets by id
42
+ # alone, so a typed through walks its join records instead.
43
+ # : (untyped) -> bool
44
+ def pt_at_source?: (untyped) -> bool
45
+
33
46
  # : (untyped, untyped, untyped) -> Array[untyped]
34
47
  def through_members: (untyped, untyped, untyped) -> Array[untyped]
35
48
 
@@ -16,8 +16,10 @@ module PaperTrailDiff
16
16
  # : (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
17
17
  def initialize: (untyped, predicate: untyped, time_range: TimeRange?, limit: Integer, max_versions: Integer) -> void
18
18
 
19
- # : (Array[String]) -> Array[String]
20
- def call: (Array[String]) -> Array[String]
19
+ # More matches than the limit raise, unless the caller does not count
20
+ # them: candidates it only lists, such as deleted roots.
21
+ # : (Array[String], ?counted: bool) -> Array[String]
22
+ def call: (Array[String], ?counted: bool) -> Array[String]
21
23
 
22
24
  private
23
25
 
@@ -38,6 +40,14 @@ module PaperTrailDiff
38
40
  # : (untyped) -> untyped
39
41
  def validate_predicate: (untyped) -> untyped
40
42
 
43
+ # Expected and recorded values compare as the attribute casts them, as
44
+ # `where` reads its values: an enum's symbol names its stored value, and a
45
+ # `json` or `jsonb` version column, which PaperTrail does not cast, holds
46
+ # dates and times as strings. Casting also copies a mutable value, so the
47
+ # filter keeps its own.
48
+ # : (String, untyped) -> untyped
49
+ def cast: (String, untyped) -> untyped
50
+
41
51
  # : (untyped) -> Integer
42
52
  def validate_budget: (untyped) -> Integer
43
53
 
@@ -1,53 +1,49 @@
1
1
  # Generated from lib/paper_trail_diff/historical_snapshot_store.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Reconstructs and caches immutable historical snapshots for one adapter configuration.
4
+ # Reconstructs and caches immutable historical snapshots for one adapter
5
+ # configuration. It keeps the histories batches prepare, by root version;
6
+ # one prepared for a single root goes back to the caller, who passes it to
7
+ # every read for that root.
5
8
  class HistoricalSnapshotStore
6
9
  # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
7
10
  def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
8
11
 
9
- # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
10
- def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
12
+ # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
13
+ def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
11
14
 
12
15
  # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
13
16
  def prepare_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
14
17
 
15
- # Missing roots have no live graph to collect. Reading their associations
16
- # here would issue a query per root and seed nonexistent rows as live state.
18
+ # Missing roots, and roots compared only between versions, have no live
19
+ # graph to collect. Reading their associations here would issue a query
20
+ # per root and seed nonexistent rows as live state.
17
21
  # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
18
22
  def prepare_deleted_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
19
23
 
20
- # : (untyped, untyped) -> RecordSnapshot?
21
- def call: (untyped, untyped) -> RecordSnapshot?
24
+ # `history` is the one `prepare` returned for this root, if any.
25
+ # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
26
+ def call: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
22
27
 
23
- # : (untyped, untyped) -> RecordSnapshot?
24
- def uncached: (untyped, untyped) -> RecordSnapshot?
28
+ # : (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
29
+ def uncached: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
25
30
 
26
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
27
- def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
31
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
32
+ def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
28
33
 
29
- # : (untyped, habtm_version: untyped) -> untyped
30
- def association_reader: (untyped, habtm_version: untyped) -> untyped
31
-
32
- # : () -> PreparedActivityIndex?
33
- def activity_index: () -> PreparedActivityIndex?
34
-
35
- # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
36
- def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
37
-
38
- # : (untyped, ?direct: bool) -> [bool, untyped]
39
- def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
34
+ # : (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
35
+ def association_reader: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
40
36
 
41
37
  private
42
38
 
43
39
  @live_graph_collector: LiveGraphCollector
44
40
 
41
+ @live_roots: Hash[identity, untyped]
42
+
45
43
  @normalizer: SnapshotNormalizer
46
44
 
47
45
  @prepared_histories: Hash[Array[untyped], PreparedHistory]
48
46
 
49
- @prepared_history: PreparedHistory?
50
-
51
47
  @prepared_snapshotter: PreparedSnapshotBuilder
52
48
 
53
49
  @preparer: untyped
@@ -58,6 +54,10 @@ module PaperTrailDiff
58
54
 
59
55
  @tree: AssociationTree
60
56
 
57
+ # A batch's history for the version wins over the one a caller passes.
58
+ # : (untyped, PreparedHistory?) -> PreparedHistory?
59
+ def history_for: (untyped, PreparedHistory?) -> PreparedHistory?
60
+
61
61
  # : (untyped) -> Array[untyped]
62
62
  def context_key: (untyped) -> Array[untyped]
63
63
 
@@ -67,14 +67,20 @@ module PaperTrailDiff
67
67
  # : (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
68
68
  def register_batch: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
69
69
 
70
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
71
- def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
70
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
71
+ def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
72
+
73
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
74
+ def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
72
75
 
73
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
74
- def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
76
+ # Rebuilding a version's associations writes them onto the record, so each
77
+ # snapshot gets its own copy of a batch's loaded row, built from the row's
78
+ # stored values without a query.
79
+ # : (untyped) -> untyped
80
+ def live_root: (untyped) -> untyped
75
81
 
76
- # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
77
- def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped) -> RecordSnapshot?
82
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
83
+ def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
78
84
 
79
85
  # : (untyped, untyped) -> Array[untyped]
80
86
  def snapshot_key: (untyped, untyped) -> Array[untyped]
@@ -25,6 +25,11 @@ module PaperTrailDiff
25
25
  # : (untyped, AssociationTree) -> Array[[untyped, AssociationTree]]
26
26
  def selected_reflections: (untyped, AssociationTree) -> Array[[ untyped, AssociationTree ]]
27
27
 
28
+ # Active Record raises a bare NameError for a type that names no class, so
29
+ # each type is resolved first to raise one that names the record.
30
+ # : (Array[untyped], Array[[untyped, AssociationTree]]) -> void
31
+ def resolve_polymorphic_targets: (Array[untyped], Array[[ untyped, AssociationTree ]]) -> void
32
+
28
33
  # : (Array[untyped], Array[[untyped, AssociationTree]], individually: bool) -> void
29
34
  def preload_subtrees: (Array[untyped], Array[[ untyped, AssociationTree ]], individually: bool) -> void
30
35
 
@@ -34,9 +39,6 @@ module PaperTrailDiff
34
39
  # : () -> untyped
35
40
  def active_record_preloader: () -> untyped
36
41
 
37
- # : (untyped, untyped) -> bool
38
- def batch_safe?: (untyped, untyped) -> bool
39
-
40
42
  # : (Array[untyped], untyped) -> Array[untyped]
41
43
  def load_individually: (Array[untyped], untyped) -> Array[untyped]
42
44
 
@@ -43,6 +43,7 @@ module PaperTrailDiff
43
43
  # Returns the changed paths, or an empty hash when the pair is not two
44
44
  # structures this can look inside. An empty result therefore means "nothing
45
45
  # to report at this depth", and the caller still has the whole-value change.
46
+ # Two arrays at the top are one membership change, at the empty path.
46
47
  # : () -> nested_changes
47
48
  def call: () -> nested_changes
48
49
 
@@ -52,14 +53,16 @@ module PaperTrailDiff
52
53
 
53
54
  @to_value: untyped
54
55
 
55
- # Both sides have to be readable as a Hash for a nested answer to mean
56
- # anything. A column that held text on one side and JSON on the other
57
- # changed wholesale, and saying so is the accurate report.
58
- # : () -> [Hash[untyped, untyped]?, Hash[untyped, untyped]?]
59
- def structures: () -> [ Hash[untyped, untyped]?, Hash[untyped, untyped]? ]
56
+ # Both sides have to be readable as the same kind of structure for a
57
+ # nested answer to mean anything. A column that held text on one side and
58
+ # JSON on the other changed wholesale, and saying so is the accurate report.
59
+ # : () -> [untyped, untyped]
60
+ def structures: () -> [ untyped, untyped ]
60
61
 
61
- # : (untyped) -> Hash[untyped, untyped]?
62
- def structure: (untyped) -> Hash[untyped, untyped]?
62
+ # A string is read as JSON; anything else, or JSON that is neither an
63
+ # object nor an array, is left for #call to decline.
64
+ # : (untyped) -> untyped
65
+ def structure: (untyped) -> untyped
63
66
 
64
67
  # : (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void
65
68
  def walk: (Hash[untyped, untyped], Hash[untyped, untyped], Array[String], nested_changes) -> void