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
@@ -1,31 +1,76 @@
1
1
  # Generated from lib/paper_trail_diff/prepared_state_association_reader.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Reads plain direct edges without creating AR records for their members.
4
+ # Reads plain edges without creating AR records for their members: direct
5
+ # edges, polymorphic `belongs_to`, and `has_many :through` built from them.
5
6
  class PreparedStateAssociationReader
6
- # : (PreparedRecordIndex, untyped) -> void
7
- def initialize: (PreparedRecordIndex, untyped) -> void
7
+ # : (PreparedRecordIndex, untyped, ScopeCondition::Cache) -> void
8
+ def initialize: (PreparedRecordIndex, untyped, ScopeCondition::Cache) -> void
8
9
 
9
- # : (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
10
- def call: (PreparedRecordState, untyped, untyped) -> [ bool, Array[PreparedRecordState] ]
10
+ # Unranked, as a part of a has_many through is read, it returns every row
11
+ # the part's conditions admit, a record reached twice appearing twice.
12
+ # : (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [bool, Array[PreparedRecordState]]
13
+ def call: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [ bool, Array[PreparedRecordState] ]
11
14
 
12
15
  private
13
16
 
17
+ @conditions: ScopeCondition::Cache
18
+
14
19
  @edges: untyped
15
20
 
16
21
  @records: PreparedRecordIndex
17
22
 
18
- # : (untyped) -> bool
19
- def supported?: (untyped) -> bool
23
+ # A polymorphic target's class is known only once a record names it, so
24
+ # `target` reads its scope for each record instead.
25
+ # : (untyped, bool) -> bool
26
+ def supported?: (untyped, bool) -> bool
27
+
28
+ # : (PreparedRecordState, untyped, bool, ?untyped) -> bool
29
+ def in_scope?: (PreparedRecordState, untyped, bool, ?untyped) -> bool
30
+
31
+ # A type that names no class, or a class whose scope cannot be read as
32
+ # conditions, is left to the record path, which raises for the first and
33
+ # reads the second through its association.
34
+ # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
35
+ def target: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
36
+
37
+ # : (PreparedRecordState, untyped) -> untyped
38
+ def target_class: (PreparedRecordState, untyped) -> untyped
39
+
40
+ # The members of each join record the owner had at the boundary, as
41
+ # PreparedHistory#through_records reads them from records. Under
42
+ # `source_type:`, only join records of that type count. A has_many
43
+ # through reads its parts unranked, as its query does.
44
+ # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
45
+ def through: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
20
46
 
21
- # : (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
22
- def children: (PreparedRecordState, untyped, untyped) -> [ bool, Array[PreparedRecordState] ]
47
+ # The through's own scope applies after its parts' scopes, to each row,
48
+ # and a ranked read then keeps a record reached twice as one member.
49
+ # : (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
50
+ def through_members: (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
51
+
52
+ # A has_one keeps the first of its records.
53
+ # : (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
54
+ def first_if_one: (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
55
+
56
+ # : (untyped, PreparedRecordState) -> bool
57
+ def typed_join?: (untyped, PreparedRecordState) -> bool
58
+
59
+ # A record reached through two join records is one member.
60
+ # : (PreparedRecordState) -> Array[untyped]
61
+ def identity: (PreparedRecordState) -> Array[untyped]
62
+
63
+ # : (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
64
+ def children: (PreparedRecordState, untyped, untyped, bool) -> [ bool, Array[PreparedRecordState] ]
23
65
 
24
66
  # : (untyped, PreparedRecordState) -> Array[untyped]
25
67
  def ids_for: (untyped, PreparedRecordState) -> Array[untyped]
26
68
 
27
- # : (PreparedRecordState, PreparedRecordState, untyped) -> bool
28
- def member?: (PreparedRecordState, PreparedRecordState, untyped) -> bool
69
+ # : (PreparedRecordState, PreparedRecordState, untyped, bool) -> bool
70
+ def member?: (PreparedRecordState, PreparedRecordState, untyped, bool) -> bool
71
+
72
+ # : (PreparedRecordState) -> String
73
+ def owner_id: (PreparedRecordState) -> String
29
74
 
30
75
  # : (PreparedRecordState, untyped, untyped) -> bool
31
76
  def matching_type?: (PreparedRecordState, untyped, untyped) -> bool
@@ -0,0 +1,47 @@
1
+ # Generated from lib/paper_trail_diff/recorded_changes.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # The changes PaperTrail wrote with one version, typed by the version's model.
5
+ #
6
+ # A step's diff compares reconstructed states, so it also holds whatever was
7
+ # saved without a version before the next one was read. This is the other
8
+ # account of the same event: only what PaperTrail recorded for it. Comparing
9
+ # the two is how a caller tells an unrecorded write from the event's own edit.
10
+ #
11
+ # PaperTrail's `version.changeset` finds the model through `version.item`,
12
+ # which is a query per version and nothing at all once the record is deleted.
13
+ # The version already names its model, so neither is needed here.
14
+ class RecordedChanges
15
+ IGNORE_NAMES_REQUIRED: ::String
16
+
17
+ # : (untyped, ignore: untyped) -> Hash[String, ValueChange]?
18
+ def self.call: (untyped, ignore: untyped) -> Hash[String, ValueChange]?
19
+
20
+ # : (untyped, ignore: untyped) -> void
21
+ def initialize: (untyped, ignore: untyped) -> void
22
+
23
+ # : () -> Hash[String, ValueChange]?
24
+ def call: () -> Hash[String, ValueChange]?
25
+
26
+ private
27
+
28
+ @ignore: untyped
29
+
30
+ @version: untyped
31
+
32
+ # Validated before anything is read, so a bad option fails the same way
33
+ # whether or not this version happened to record changes. Subclasses of
34
+ # Array and String pass, as in other methods' `ignore:`; Symbol has none.
35
+ # : () -> Array[String]
36
+ def ignored_names: () -> Array[String]
37
+
38
+ # Without the column, or with it left empty for this version, nothing was
39
+ # recorded. That is not the same answer as a recorded empty changeset.
40
+ # : () -> bool
41
+ def recorded?: () -> bool
42
+
43
+ # Primary keys identify the record rather than describe it, as in a diff.
44
+ # : (untyped, Array[String]) -> Hash[String, ValueChange]
45
+ def value_changes: (untyped, Array[String]) -> Hash[String, ValueChange]
46
+ end
47
+ end
@@ -0,0 +1,22 @@
1
+ # Generated from lib/paper_trail_diff/recorded_class.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # The class a record had at one version, which decides the associations it
5
+ # can have. Without an `item_subtype` column PaperTrail stores only the base
6
+ # class, so an STI subclass is read from the stored inheritance column: the
7
+ # state before the change, or for a create, the value it was created with.
8
+ # A version that stored neither stays on the base class.
9
+ module RecordedClass
10
+ # : (untyped) -> untyped
11
+ def self?.for: (untyped) -> untyped
12
+
13
+ # : (untyped) -> bool
14
+ def self?.sti_base?: (untyped) -> bool
15
+
16
+ # : (untyped, untyped) -> untyped
17
+ def self?.stored_type: (untyped, untyped) -> untyped
18
+
19
+ # : (StandardError) -> bool
20
+ def self?.subclass_not_found?: (StandardError) -> bool
21
+ end
22
+ end
@@ -13,6 +13,8 @@ module PaperTrailDiff
13
13
  # An error is a specification, so it names the way out as well as the wall.
14
14
  # A window ending at the present can never gain a later version, which makes
15
15
  # "write a checkpoint afterwards" impossible advice on its own.
16
+ # A window closes on the current record when it reaches the present, so
17
+ # this is raised only when there is none to read.
16
18
  INCOMPLETE: ::String
17
19
 
18
20
  # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
@@ -0,0 +1,219 @@
1
+ # Generated from lib/paper_trail_diff/scope_condition.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # An association scope, or its target's default scope, read as conditions
5
+ # on stored attributes, so membership at a boundary can be decided from each
6
+ # record's state there rather than by a query. A limit, offset or has_one
7
+ # order then ranks the records that meet the conditions (ScopeRanking). It
8
+ # reads the relation the scope builds once and never runs application code
9
+ # per record. A scope it cannot read exactly builds no condition, and the
10
+ # caller keeps its slower path.
11
+ class ScopeCondition
12
+ # Relation parts that leave membership to the where clause and the
13
+ # ranking alone.
14
+ RELATION_VALUES: untyped
15
+
16
+ # Relation parts that load or shape rows without choosing them.
17
+ LOADING_VALUES: untyped
18
+
19
+ # Types whose stored values compare in Ruby as the database compares them,
20
+ # named rather than referenced so that loading needs no Active Model.
21
+ VALUE_TYPES: untyped
22
+
23
+ TEXT_TYPE: ::String
24
+
25
+ ENUM_TYPE: ::String
26
+
27
+ BIND_PARAM: ::String
28
+
29
+ ATTRIBUTE: ::String
30
+
31
+ # Adapters that compare strings exactly by default. MySQL and SQL Server
32
+ # ignore case and trailing spaces by default, which Ruby cannot follow.
33
+ EXACT_TEXT_ADAPTERS: untyped
34
+
35
+ # Raised while reading a node that has no exact plain-Ruby reading.
36
+ class Unreadable < StandardError
37
+ end
38
+
39
+ # Whether the reflection filters its target beyond its keys at all.
40
+ # : (untyped) -> bool
41
+ def self.scoped?: (untyped) -> bool
42
+
43
+ # A through also filters by the scopes of each reflection it passes.
44
+ # : (untyped) -> bool
45
+ def self.scoped_path?: (untyped) -> bool
46
+
47
+ # Returns nil when the scope cannot be read as plain conditions and an
48
+ # exact ranking. A part of a has_many through is read unranked: the
49
+ # through's query keeps only its conditions.
50
+ # : (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
51
+ def self.build: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
52
+
53
+ # A relation's own where clause, default scope included, read as
54
+ # conditions on stored attributes; nil when it cannot be. Its order,
55
+ # limit, and offset choose a page of current rows rather than membership,
56
+ # and loading or selecting columns changes neither, so they are left out.
57
+ # A single-table subclass's type condition is left to the caller, as for
58
+ # an association.
59
+ # : (untyped, untyped) -> ScopeCondition?
60
+ def self.for_relation: (untyped, untyped) -> ScopeCondition?
61
+
62
+ # nil when the relation picks its members by conditions alone.
63
+ # : (untyped, untyped, untyped) -> ScopeRanking?
64
+ def self.ranking: (untyped, untyped, untyped) -> ScopeRanking?
65
+
66
+ # A has_one through orders its rows by its own order and then its parts',
67
+ # and takes the first, so one that passes a ranked part is not read. A
68
+ # has_many through keeps only its parts' conditions.
69
+ # : (untyped) -> bool
70
+ def self.ranked_through?: (untyped) -> bool
71
+
72
+ # Whether any part of a through, at any depth, has a limit, an offset or
73
+ # a has_one order.
74
+ # : (untyped) -> bool
75
+ def self.ranked_parts?: (untyped) -> bool
76
+
77
+ # A polymorphic part's class, and so its scope, is known only per record.
78
+ # : (untyped) -> bool
79
+ def self.ranked_part?: (untyped) -> bool
80
+
81
+ # A scope that takes the owner differs per record, so it is never read.
82
+ # : (untyped, untyped) -> untyped
83
+ def self.scoped_relation: (untyped, untyped) -> untyped
84
+
85
+ # Some parts, such as the having clause `or` sets, may be present but
86
+ # empty.
87
+ # : (untyped) -> bool
88
+ def self.plain_relation?: (untyped) -> bool
89
+
90
+ # : (untyped, Array[untyped], ?ScopeRanking?) -> void
91
+ def initialize: (untyped, Array[untyped], ?ScopeRanking?) -> void
92
+
93
+ # SQL admits a row only when its condition is true, not when it is
94
+ # unknown.
95
+ # : (Hash[String, untyped]) -> bool
96
+ def matches?: (Hash[String, untyped]) -> bool
97
+
98
+ # The members among records that are each the owner's by key: those that
99
+ # meet the conditions, then ranked.
100
+ # : (Array[untyped]) -> Array[untyped]
101
+ def members: (Array[untyped]) -> Array[untyped]
102
+
103
+ # Records that meet the conditions, as ranked; unchanged without a
104
+ # ranking.
105
+ # : (Array[untyped]) -> Array[untyped]
106
+ def rank: (Array[untyped]) -> Array[untyped]
107
+
108
+ # SQL's three values: a comparison with NULL is unknown (nil) rather than
109
+ # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
110
+ # is always known. Unknown matters only under NOT, which leaves it
111
+ # unknown where false would become true.
112
+ COMPARISONS: untyped
113
+
114
+ private
115
+
116
+ @model_class: untyped
117
+
118
+ @predicate: Array[untyped]
119
+
120
+ @ranking: ScopeRanking?
121
+
122
+ # true, false, or nil for unknown.
123
+ # : (Array[untyped], Hash[String, untyped]) -> bool?
124
+ def evaluate: (Array[untyped], Hash[String, untyped]) -> bool?
125
+
126
+ # False if any part is, otherwise unknown if any part is.
127
+ # : (Array[bool?]) -> bool?
128
+ def all: (Array[bool?]) -> bool?
129
+
130
+ # True if any part is, otherwise unknown if any part is.
131
+ # : (Array[bool?]) -> bool?
132
+ def any: (Array[bool?]) -> bool?
133
+
134
+ # : (bool?) -> bool?
135
+ def negate: (bool?) -> bool?
136
+
137
+ # The form the database holds, as the scope's own values were cast.
138
+ # : (String, Hash[String, untyped]) -> untyped
139
+ def stored: (String, Hash[String, untyped]) -> untyped
140
+
141
+ # Builds each reflection's condition once per target class.
142
+ class Cache
143
+ # : () -> void
144
+ def initialize: () -> void
145
+
146
+ # nil when the scope cannot be read from stored attributes.
147
+ # : (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
148
+ def call: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
149
+
150
+ # The records the reflection's scope admits, as it ranks them. Its
151
+ # condition must exist.
152
+ # : (untyped, Array[untyped], ?untyped, ranked: bool) -> Array[untyped]
153
+ def select: (untyped, Array[untyped], ?untyped, ranked: bool) -> Array[untyped]
154
+
155
+ @conditions: Hash[Array[untyped], ScopeCondition?]
156
+ end
157
+
158
+ # Compiles a where clause into nested arrays of plain comparisons.
159
+ class Reader
160
+ # : (untyped) -> void
161
+ def initialize: (untyped) -> void
162
+
163
+ # : (untyped) -> Array[untyped]
164
+ def call: (untyped) -> Array[untyped]
165
+
166
+ private
167
+
168
+ @model_class: untyped
169
+
170
+ # An Or is binary before Rails 7.2 and n-ary from it.
171
+ # : (untyped) -> Array[untyped]
172
+ def either: (untyped) -> Array[untyped]
173
+
174
+ # : (untyped) -> Array[untyped]
175
+ def comparison: (untyped) -> Array[untyped]
176
+
177
+ # Whether a value is NULL compares alike on every type.
178
+ # : (Symbol, untyped) -> Array[untyped]
179
+ def binary: (Symbol, untyped) -> Array[untyped]
180
+
181
+ # : (untyped) -> Array[untyped]
182
+ def homogeneous_in: (untyped) -> Array[untyped]
183
+
184
+ # Active Record writes an empty NOT IN as a condition that is always
185
+ # true, and a NOT IN list holding NULL matches no row.
186
+ # : (Symbol, untyped, Array[untyped]) -> Array[untyped]
187
+ def list: (Symbol, untyped, Array[untyped]) -> Array[untyped]
188
+
189
+ # Ruby comparison stands in for SQL only on the record's own column of
190
+ # a type both compare alike. Whether a value is NULL, any column's
191
+ # type compares alike.
192
+ # : (untyped, ?null_test: bool) -> String
193
+ def column: (untyped, ?null_test: bool) -> String
194
+
195
+ # : (String, untyped) -> bool
196
+ def comparable?: (String, untyped) -> bool
197
+
198
+ # PostgreSQL's citext is text that compares without regard to case.
199
+ # : (untyped) -> bool
200
+ def exact_text?: (untyped) -> bool
201
+
202
+ # An enum compares the values it stores, which its subtype describes. A
203
+ # wrapper such as a serialized or encrypted type is none of these.
204
+ # : (untyped) -> untyped
205
+ def value_type: (untyped) -> untyped
206
+
207
+ # A list that is not plain values, such as a subquery, is unreadable.
208
+ # : (untyped) -> Array[untyped]
209
+ def values: (untyped) -> Array[untyped]
210
+
211
+ # A value out of the column's range makes Active Record write a
212
+ # constant condition instead, so it is left unread. Active Record
213
+ # writes IS NULL for a value that is nil before casting, but `= NULL`,
214
+ # which matches nothing, for one that only casts to nil.
215
+ # : (untyped) -> untyped
216
+ def value: (untyped) -> untyped
217
+ end
218
+ end
219
+ end
@@ -0,0 +1,125 @@
1
+ # Generated from lib/paper_trail_diff/scope_ranking.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # The order, offset and limit by which a scope picks its members from the
5
+ # records that meet its conditions, as the database would rank them. It is
6
+ # read only when the order is total and every key compares in Ruby as SQL
7
+ # compares it; otherwise build returns nil and the caller keeps its slower
8
+ # path.
9
+ class ScopeRanking
10
+ DIRECTIONS: untyped
11
+
12
+ ATTRIBUTE: ::String
13
+
14
+ ENUM_TYPE: ::String
15
+
16
+ # Rails wraps a time-zone-aware attribute's type, by default every
17
+ # datetime's, in this delegator; the time it stores is the wrapped type's.
18
+ TIME_ZONE_TYPE: ::String
19
+
20
+ # Integers, booleans and dates sort alike everywhere. Strings follow a
21
+ # collation, so they are not read.
22
+ ORDER_TYPES: untyped
23
+
24
+ # Times sort alike only at the precision both the column and history
25
+ # keep. A time of day is not read: in memory it keeps the date it was
26
+ # given, which the database drops.
27
+ DATETIME_TYPE: ::String
28
+
29
+ # Where each adapter sorts NULL in an ascending order by default; a
30
+ # descending order reverses it. Another adapter's ranking is not read.
31
+ NULLS_LAST: untyped
32
+
33
+ # Places in a sort key, of which only the order counts: a value between a
34
+ # NULL sorted first and one sorted last, and false before true. Every
35
+ # value is a number, so that a descending key can negate it.
36
+ NULL_PLACE: untyped
37
+
38
+ VALUE_PLACE: ::Integer
39
+
40
+ BOOLEAN_VALUE: untyped
41
+
42
+ # Whether the relation picks members by rank rather than by condition
43
+ # alone. A has_one takes the first record its order names.
44
+ # : (untyped, untyped) -> bool
45
+ def self.ranks?: (untyped, untyped) -> bool
46
+
47
+ # A has_many, through or not, or a direct has_one is ranked per owner as
48
+ # its own query ranks it. A has_many through ranks the rows its join
49
+ # yields, a record reached twice counting twice, by its own order first.
50
+ # Returns nil when the ranking cannot be read exactly.
51
+ # : (untyped, untyped, untyped) -> ScopeRanking?
52
+ def self.build: (untyped, untyped, untyped) -> ScopeRanking?
53
+
54
+ # : (untyped) -> bool
55
+ def self.own?: (untyped) -> bool
56
+
57
+ # Active Record casts a limit to an integer but keeps an offset as given,
58
+ # which may be a String or SQL.
59
+ # : (untyped) -> bool
60
+ def self.plain_offset?: (untyped) -> bool
61
+
62
+ # The order's keys up to the primary key, which makes it total. Keys
63
+ # after it never decide anything.
64
+ # : (Array[untyped], untyped) -> Array[[String, bool]]?
65
+ def self.keys: (Array[untyped], untyped) -> Array[[ String, bool ]]?
66
+
67
+ # The record's own column, sorted plainly in one direction.
68
+ # : (untyped, untyped) -> String?
69
+ def self.column: (untyped, untyped) -> String?
70
+
71
+ # : (untyped, String) -> bool
72
+ def self.orderable?: (untyped, String) -> bool
73
+
74
+ # The type of the value a column stores, under an enum or time zone wrapper.
75
+ # : (untyped) -> untyped
76
+ def self.stored_type: (untyped) -> untyped
77
+
78
+ # Active Record truncates a time to its column's precision before writing
79
+ # it, so history holds the stored value when it keeps that many digits.
80
+ # Times the type stores in UTC sort as the instants they name; local
81
+ # times repeat an hour when clocks go back.
82
+ # : (untyped, untyped) -> bool
83
+ def self.exact_time?: (untyped, untyped) -> bool
84
+
85
+ # : (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
86
+ def initialize: (untyped, Array[[ String, bool ]], bool, Integer?, Integer?) -> void
87
+
88
+ # The members among records that met the scope's conditions, in order.
89
+ # : (Array[untyped]) -> Array[untyped]
90
+ def call: (Array[untyped]) -> Array[untyped]
91
+
92
+ private
93
+
94
+ @keys: Array[[ String, bool ]]
95
+
96
+ @limit: Integer?
97
+
98
+ @model_class: untyped
99
+
100
+ @nulls_last: bool
101
+
102
+ @offset: Integer?
103
+
104
+ # Keys compare in turn, and the primary key always decides. A descending
105
+ # key negates its places, which also moves NULL to the other end, as each
106
+ # adapter does by default.
107
+ # : (Hash[String, untyped]) -> Array[Array[Numeric]]
108
+ def sort_key: (Hash[String, untyped]) -> Array[Array[Numeric]]
109
+
110
+ # NULL holds the adapter's place alone, so it never compares as a value.
111
+ # A version saved before its column existed holds NULL there too.
112
+ # : (untyped) -> Array[Numeric]
113
+ def place: (untyped) -> Array[Numeric]
114
+
115
+ # A time as its seconds, exactly, and a date as its day number.
116
+ # : (untyped) -> Numeric
117
+ def number: (untyped) -> Numeric
118
+
119
+ # The value the database sorts by, as the key's type casts it. An enum
120
+ # sorts by the integer it stores; other types are compared cast, since an
121
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
122
+ # : (String, Hash[String, untyped]) -> untyped
123
+ def stored: (String, Hash[String, untyped]) -> untyped
124
+ end
125
+ end
@@ -29,6 +29,12 @@ module PaperTrailDiff
29
29
  # : (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
30
30
  def initialize: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
31
31
 
32
+ # Each root's change rows, keyed as `analyses` is: the roots that still
33
+ # exist, then the deleted ones that have history to report. A deleted root
34
+ # without destroy history has no rows and is left out.
35
+ # : () -> Hash[Array[String], Array[ChangeRow]]
36
+ def change_rows: () -> Hash[Array[String], Array[ChangeRow]]
37
+
32
38
  # Two elements, not three: `roots` is reached by name so that existing
33
39
  # destructuring keeps working.
34
40
  # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
@@ -3,17 +3,22 @@
3
3
  module PaperTrailDiff
4
4
  # Selects both populations and checks their shared ceiling before analysis.
5
5
  class ScopedAnalysisBuilder
6
- # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
7
- def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped) -> void
6
+ # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
7
+ def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
8
8
 
9
9
  # : () -> ScopedAnalysis
10
10
  def call: () -> ScopedAnalysis
11
11
 
12
+ private
13
+
14
+ # : (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
15
+ def analysis: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
16
+
12
17
  @analyzer: untyped
13
18
 
14
19
  @deleted_analyzer: untyped
15
20
 
16
- @include_deleted: bool
21
+ @deleted_filter: DeletedRootFilter?
17
22
 
18
23
  @limit: Integer
19
24
 
@@ -38,8 +38,11 @@ module PaperTrailDiff
38
38
  def initialize: (records: Array[untyped], unreachable: Array[Array[String]]) -> void
39
39
  end
40
40
 
41
- # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
42
- def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
41
+ # `activity_tree` names the association paths whose changes also select a
42
+ # root, as an activity analysis reports them. Without one, only a root's
43
+ # own versions select it.
44
+ # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
45
+ def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
43
46
 
44
47
  # : () -> Result
45
48
  def call: () -> Result
@@ -50,6 +53,8 @@ module PaperTrailDiff
50
53
 
51
54
  @limit: Integer
52
55
 
56
+ @related: AssociationActivitySelection?
57
+
53
58
  @scope: untyped
54
59
 
55
60
  @time_range: TimeRange?
@@ -59,14 +64,34 @@ module PaperTrailDiff
59
64
  # in the window -- not to the relation or `limit:` -- so a report on one
60
65
  # record could read every id in a busy table. A subquery keeps the work
61
66
  # bounded by what the relation and the deletions actually contain.
62
- # : () -> Result
63
- def database_selection: () -> Result
67
+ # : (Array[AssociationActivitySelection::Query]) -> Result
68
+ def database_selection: (Array[AssociationActivitySelection::Query]) -> Result
69
+
70
+ # Comparing in SQL needs every subquery's column to share the key's type.
71
+ # : (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
72
+ def subqueries: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
73
+
74
+ # Which candidates still have a row is asked without the relation's
75
+ # conditions, so that "filtered out" and "no longer exists" stay
76
+ # separable. A filter then reads the history of the relation's records
77
+ # only, whose order and page choose among those that match, and of the
78
+ # deleted ones, which no relation can test. Those it lists, as without a
79
+ # filter, but does not count toward `limit:`.
80
+ # : (Array[String]) -> Result
81
+ def plucked_selection: (Array[String]) -> Result
64
82
 
65
83
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
66
- # rejects an integer key against a string item_id outright.
84
+ # rejects an integer key against a string item_id outright. A composite
85
+ # key names no single attribute, so it has no type and never matches.
67
86
  # : () -> bool
68
87
  def comparable_keys?: () -> bool
69
88
 
89
+ # : () -> Symbol?
90
+ def key_type: () -> Symbol?
91
+
92
+ # : (Array[AssociationActivitySelection::Query]) -> Array[String]
93
+ def related_missing_ids: (Array[AssociationActivitySelection::Query]) -> Array[String]
94
+
70
95
  # Changed in the window but without a row, found with an anti-join instead
71
96
  # of comparing two plucked lists.
72
97
  # : () -> Array[String]
@@ -81,6 +106,10 @@ module PaperTrailDiff
81
106
  # : (untyped) -> untyped
82
107
  def normalize_scope: (untyped) -> untyped
83
108
 
109
+ # : () -> void
110
+ def reject_unversioned!: () -> void
111
+
112
+ # No Integer subclass has instances, so this is `is_a?` by another name.
84
113
  # : (Integer) -> Integer
85
114
  def validate_limit: (Integer) -> Integer
86
115
 
@@ -90,16 +119,19 @@ module PaperTrailDiff
90
119
  # : () -> Array[String]
91
120
  def versioned_ids: () -> Array[String]
92
121
 
93
- # Which of those candidates still have a row, asked without the relation's
94
- # conditions so that "filtered out" and "no longer exists" stay separable.
95
- # : (Array[String]) -> Array[String]
96
- def live_ids: (Array[String]) -> Array[String]
122
+ # : (untyped, Array[String]) -> Array[String]
123
+ def ids_in: (untyped, Array[String]) -> Array[String]
97
124
 
98
125
  # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
99
126
  # relation may order by joined columns or select a PostgreSQL json column.
100
127
  # Read bounded pages until the relation ends or too many unique roots appear.
101
- # : (untyped) -> Array[untyped]
102
- def selected_records: (untyped) -> Array[untyped]
128
+ # Each candidate source is an id list or a subquery; a record matching any
129
+ # of them is selected.
130
+ # : (Array[untyped]) -> Array[untyped]
131
+ def selected_records: (Array[untyped]) -> Array[untyped]
132
+
133
+ # : (Array[untyped]) -> untyped
134
+ def candidate_relation: (Array[untyped]) -> untyped
103
135
 
104
136
  # : (untyped, Integer) -> Array[untyped]
105
137
  def record_page: (untyped, Integer) -> Array[untyped]
@@ -121,6 +153,12 @@ module PaperTrailDiff
121
153
  # : () -> String
122
154
  def item_type: () -> String
123
155
 
156
+ # A relation delegates class methods to its model, so every mutation here,
157
+ # which drops `.model`, answers the same.
158
+ # mutant:disable
159
+ # : () -> untyped
160
+ def model: () -> untyped
161
+
124
162
  # : () -> untyped
125
163
  def base_class: () -> untyped
126
164