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
@@ -0,0 +1,112 @@
1
+ # Generated from lib/paper_trail_diff/association_activity_selection.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Finds the roots whose requested associations changed in a window, so that
5
+ # selecting by activity includes a record whose own row did not change.
6
+ #
7
+ # A root qualifies when a record on one of its requested paths has a version
8
+ # in the window while it belonged to that root: when the window opened, or
9
+ # after a change inside it. Those are the memberships PT-AT recorded, and the
10
+ # ones an activity analysis reads. For `has_many :through`, the join rows are
11
+ # on the path too, since creating or destroying one changes membership.
12
+ #
13
+ # Each edge is one query, walked from the leaves toward the root, never one
14
+ # per root. Ids stay in a subquery while the columns compared share a type;
15
+ # otherwise they are read and the edge runs over them in slices.
16
+ class AssociationActivitySelection
17
+ SLICE: ::Integer
18
+
19
+ # The ids a one-column subquery selects, with that column's type: a
20
+ # database compares columns of one type only, and PostgreSQL rejects an
21
+ # integer key against a string item_id outright.
22
+ class Query
23
+ attr_reader relation: untyped
24
+
25
+ attr_reader column: untyped
26
+
27
+ attr_reader type: Symbol?
28
+
29
+ # : (untyped, untyped, Symbol?) -> void
30
+ def initialize: (untyped, untyped, Symbol?) -> void
31
+
32
+ # A key PT-AT recorded as empty names no record, so it is left out.
33
+ # : () -> Array[untyped]
34
+ def values: () -> Array[untyped]
35
+
36
+ # The ids with no match in `keys`, a subquery of the keys that exist.
37
+ # : (untyped) -> Array[untyped]
38
+ def missing: (untyped) -> Array[untyped]
39
+ end
40
+
41
+ type source = Query | Array[untyped]
42
+
43
+ # Every id the sources name, read from the database where needed.
44
+ # : (Array[source]) -> Array[untyped]
45
+ def self.values: (Array[source]) -> Array[untyped]
46
+
47
+ # : (untyped, tree: AssociationTree, time_range: TimeRange?) -> void
48
+ def initialize: (untyped, tree: AssociationTree, time_range: TimeRange?) -> void
49
+
50
+ # The roots' ids, each source a subquery or an array of values.
51
+ # : () -> Array[source]
52
+ def call: () -> Array[source]
53
+
54
+ private
55
+
56
+ @model: untyped
57
+
58
+ @time_range: TimeRange?
59
+
60
+ @traversal: AssociationTraversal
61
+
62
+ # Ids of `model` records with a change somewhere below them in `tree`: the
63
+ # targets that changed, or that reach a change further down.
64
+ # : (untyped, AssociationTree, String) -> Array[source]
65
+ def reach: (untyped, AssociationTree, String) -> Array[source]
66
+
67
+ # : (untyped, Array[source]) -> Array[source]
68
+ def owners: (untyped, Array[source]) -> Array[source]
69
+
70
+ # A join row that changes moves membership as surely as a target that does.
71
+ # : (untyped, Array[source]) -> Array[source]
72
+ def through_owners: (untyped, Array[source]) -> Array[source]
73
+
74
+ # Under `source_type:`, only join rows of that type are members, so only
75
+ # targets of that type and changes to those rows count.
76
+ # : (untyped, Array[source], untyped) -> Array[source]
77
+ def typed_joins: (untyped, Array[source], untyped) -> Array[source]
78
+
79
+ # A polymorphic key's targets are known only from the types its rows name,
80
+ # and a path stops at one, so only the targets' own changes count.
81
+ # : (untyped) -> Array[source]
82
+ def polymorphic_owners: (untyped) -> Array[source]
83
+
84
+ # : (untyped) -> Array[AssociationActivityEdge]
85
+ def edges: (untyped) -> Array[AssociationActivityEdge]
86
+
87
+ # Records with a version in the window, or only those of them `item_ids`
88
+ # selects: under `source_type:`, the join rows that had that type.
89
+ # : (untyped, ?untyped) -> Array[source]
90
+ def changed: (untyped, ?untyped) -> Array[source]
91
+
92
+ # One edge for each source. A subquery whose column type matches the
93
+ # filtered column stays a subquery; anything else is read, and the edge
94
+ # runs over its values in slices.
95
+ # : (AssociationActivityEdge, Array[source]) -> Array[source]
96
+ def follow: (AssociationActivityEdge, Array[source]) -> Array[source]
97
+
98
+ # : (AssociationActivityEdge, Array[untyped]) -> Array[untyped]
99
+ def read: (AssociationActivityEdge, Array[untyped]) -> Array[untyped]
100
+
101
+ # Sources are only ever a Query or a plain Array, so the one mutation
102
+ # left, `instance_of?` for `is_a?`, cannot change an answer.
103
+ # mutant:disable
104
+ # : (source, Symbol?) -> Query?
105
+ def subquery: (source, Symbol?) -> Query?
106
+
107
+ # A type naming no class has no versions to read; `changed` skips one that
108
+ # names an unversioned class.
109
+ # : (String) -> untyped
110
+ def target_class: (String) -> untyped
111
+ end
112
+ end
@@ -45,11 +45,14 @@ module PaperTrailDiff
45
45
  # : (untyped, String, untyped, bool) -> AssociationDescriptor
46
46
  def descriptor_for: (untyped, String, untyped, bool) -> AssociationDescriptor
47
47
 
48
- # : (untyped) -> Array[untyped]
49
- def supported_reflections: (untyped) -> Array[untyped]
50
-
51
- # : (untyped, untyped) -> bool
52
- def paper_trail_versions?: (untyped, untyped) -> bool
48
+ # Only what a request accepts, so every listed path can be requested.
49
+ # : (untyped, root: bool) -> Array[untyped]
50
+ def supported_reflections: (untyped, root: bool) -> Array[untyped]
51
+
52
+ # Every request that reads history refuses a path whose target, or a
53
+ # model its has_many :through goes through, has no versions.
54
+ # : (untyped) -> bool
55
+ def unversioned?: (untyped) -> bool
53
56
 
54
57
  # : (untyped) -> untyped
55
58
  def reflection_target: (untyped) -> untyped
@@ -0,0 +1,29 @@
1
+ # Generated from lib/paper_trail_diff/association_key.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # PT-AT records which record a child pointed at by that record's id, and
5
+ # history matches children to owners and targets by id. An association
6
+ # keyed on another column (`primary_key:`) would read other records'
7
+ # history, so it is refused.
8
+ module AssociationKey
9
+ # Why the association, or a part of a through, cannot be read by id.
10
+ # : (untyped) -> String?
11
+ def self.unsupported_reason: (untyped) -> String?
12
+
13
+ # The reflection, or the first part of a through, keyed on a column other
14
+ # than its owner's or target's primary key.
15
+ # : (untyped) -> untyped
16
+ def self.keyed_part: (untyped) -> untyped
17
+
18
+ # A belongs_to names a key of its target; any other macro, one of its
19
+ # owner. A polymorphic target has no single primary key to compare with.
20
+ # : (untyped) -> bool
21
+ def self.other_key?: (untyped) -> bool
22
+
23
+ # Column names are strings once the key is, so the one mutation left,
24
+ # `eql?` for `==`, answers the same.
25
+ # mutant:disable
26
+ # : (untyped, untyped) -> bool
27
+ def self.same_column?: (untyped, untyped) -> bool
28
+ end
29
+ end
@@ -4,10 +4,84 @@ module PaperTrailDiff
4
4
  # Resolves and validates ActiveRecord reflections for a bounded association tree.
5
5
  class AssociationTraversal
6
6
  # The class a `belongs_to` points at for this record, reading a polymorphic
7
- # type column when there is one. Nil when that type names no class.
7
+ # type column when there is one. Nil when the record points at nothing.
8
8
  # : (untyped, untyped) -> untyped
9
9
  def self.belongs_to_target: (untyped, untyped) -> untyped
10
10
 
11
+ # A through with `source_type:` reaches only the join records whose type
12
+ # column names that class, as Active Record's `where(type => source_type)`.
13
+ # A through's `foreign_type` is its polymorphic source's.
14
+ # : (untyped, untyped) -> bool
15
+ def self.source_type_join?: (untyped, untyped) -> bool
16
+
17
+ # The same check for a join row read as stored attributes, given the
18
+ # value of its type column.
19
+ # : (untyped, untyped) -> bool
20
+ def self.source_type_member?: (untyped, untyped) -> bool
21
+
22
+ # The class a stored type names, or nil when it names none.
23
+ # This class defines no constants of its own, so the one mutation left,
24
+ # `const_get` on it rather than on Object, finds the same class.
25
+ # mutant:disable
26
+ # : (String) -> untyped
27
+ def self.named_class: (String) -> untyped
28
+
29
+ # A type left by a renamed or removed model names no class. Active Record
30
+ # and PT-AT raise a bare NameError for it, which does not say where it is.
31
+ # : (untyped, untyped, String) -> untyped
32
+ def self.polymorphic_target: (untyped, untyped, String) -> untyped
33
+
34
+ # Why a request cannot name this association of the model, or nil when it
35
+ # can; `root` says whether the model is the record the request compares.
36
+ # Discovery lists only the associations this accepts, so every path it
37
+ # lists can be requested. A has_many :through Active Record cannot follow
38
+ # raises Active Record's own error.
39
+ # : (untyped, untyped, root: bool) -> String?
40
+ def self.unsupported_reason: (untyped, untyped, root: bool) -> String?
41
+
42
+ # History matches records by primary key, within one set of version tables.
43
+ # : (untyped) -> String?
44
+ def self.storage_reason: (untyped) -> String?
45
+
46
+ # PT-AT records a HABTM's membership only when its owner saves a version,
47
+ # in rows keyed by transaction and association name, not by owner. A root
48
+ # checkpoint so holds the root's membership and no one else's: another
49
+ # record's HABTM would read the root's rows, or none.
50
+ # : (untyped) -> String
51
+ def self.habtm_below_root: (untyped) -> String
52
+
53
+ # PT-AT records a HABTM's membership by loading the association, scope and
54
+ # target default scope applied, so a target outside the scope when the
55
+ # owner saved is never recorded. One that enters it before the next save
56
+ # is a member then that history cannot hold.
57
+ # : (untyped, bool) -> String?
58
+ def self.habtm_reason: (untyped, bool) -> String?
59
+
60
+ # : (untyped, untyped) -> bool
61
+ def self.paper_trail_versions?: (untyped, untyped) -> bool
62
+
63
+ # Active Record joins a HABTM through a hidden model of its own, which has
64
+ # no versions and no reader that PT-AT or prepared history can follow, so a
65
+ # through that crosses one would fail partway through reconstruction.
66
+ #
67
+ # The through and source reflections of a through are the hidden ones, a
68
+ # has_many in place of each HABTM, so only the public reflection of the
69
+ # same name shows the HABTM. Active Record's own check, which it runs on
70
+ # first use anyway, explains a through it cannot follow before the chain
71
+ # below it is read.
72
+ # : (untyped) -> untyped
73
+ def self.habtm_in_chain: (untyped) -> untyped
74
+
75
+ attr_reader tree: AssociationTree
76
+
77
+ # Whether a row belongs to an association whose class is `model_class`.
78
+ # Children are found by key across the whole table, so an association to an
79
+ # STI subclass has to leave out its siblings, as Active Record's type
80
+ # condition does for the live association: the row's type must name the
81
+ # class or one of its descendants. A base class takes every row.
82
+ # : (untyped, Hash[String, untyped]) -> bool
83
+ def self.sti_member?: (untyped, Hash[String, untyped]) -> bool
84
+
11
85
  # : (AssociationTree) -> void
12
86
  def initialize: (AssociationTree) -> void
13
87
 
@@ -29,9 +103,15 @@ module PaperTrailDiff
29
103
  # : (untyped) -> void
30
104
  def reject_live_habtm_activity!: (untyped) -> void
31
105
 
106
+ # A model and a tree resolve to the same reflections wherever they are
107
+ # read: a tree is only ever walked from one place, the root tree at the
108
+ # root and a subtree below it. Beyond that, the path only names a failure,
109
+ # and a failure is not cached.
32
110
  # : (untyped, AssociationTree, path: String) -> Array[untyped]
33
111
  def reflections_for: (untyped, AssociationTree, path: String) -> Array[untyped]
34
112
 
113
+ # Active Record names keys as strings. A polymorphic child also points back
114
+ # with its type column; `type` is nil for any other.
35
115
  # : (untyped) -> Array[String]
36
116
  def incoming_relationship_columns: (untyped) -> Array[String]
37
117
 
@@ -47,19 +127,18 @@ module PaperTrailDiff
47
127
  # : (untyped, AssociationTree, path: String) -> void
48
128
  def validate_tree!: (untyped, AssociationTree, path: String) -> void
49
129
 
130
+ # A polymorphic target's class differs from record to record, so the
131
+ # associations a path names below it may not exist on every target.
132
+ # : (untyped, AssociationTree, String) -> void
133
+ def reject_polymorphic_descent!: (untyped, AssociationTree, String) -> void
134
+
50
135
  # : (untyped, AssociationTree, String) -> Array[untyped]
51
136
  def requested_reflections: (untyped, AssociationTree, String) -> Array[untyped]
52
137
 
53
- # : (untyped, String, String) -> untyped
54
- def resolve_reflection: (untyped, String, String) -> untyped
55
-
56
- # : (untyped, untyped) -> bool
57
- def paper_trail_versions?: (untyped, untyped) -> bool
138
+ # : (untyped, String, String, root: bool) -> untyped
139
+ def resolve_reflection: (untyped, String, String, root: bool) -> untyped
58
140
 
59
141
  # : (untyped) -> bool
60
142
  def habtm_reflection?: (untyped) -> bool
61
-
62
- # : (String, String) -> String
63
- def join_path: (String, String) -> String
64
143
  end
65
144
  end
@@ -0,0 +1,29 @@
1
+ # Generated from lib/paper_trail_diff/batch_preload.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Which associations Active Record's preloader loads correctly for many
5
+ # owners at once.
6
+ module BatchPreload
7
+ # The preloader applies a limit or offset to all owners' records at once,
8
+ # not to each owner's, so such an association is loaded per record. A
9
+ # has_one is no exception. Through a part with a limit, an offset or a
10
+ # has_one cut, the preloader keeps what the part alone would load, while
11
+ # the through's own query keeps the part's conditions only.
12
+ #
13
+ # The declared scope is read, not a record's association scope: Active
14
+ # Record adds `limit(1)` to every has_one's, which would load every
15
+ # has_one per record.
16
+ # : (untyped) -> bool
17
+ def self.safe?: (untyped) -> bool
18
+
19
+ # : (untyped) -> untyped
20
+ def self.declared_relation: (untyped) -> untyped
21
+
22
+ # : (untyped) -> bool
23
+ def self.cut_part?: (untyped) -> bool
24
+
25
+ # Every part a through passes, at any depth.
26
+ # : (untyped) -> Array[untyped]
27
+ def self.through_parts: (untyped) -> Array[untyped]
28
+ end
29
+ end
@@ -4,11 +4,12 @@ module PaperTrailDiff
4
4
  # Builds one root's Analysis inside a batch, from versions the batch already
5
5
  # selected and history it already prepared.
6
6
  class BatchedRootAnalyzer
7
- # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
8
- def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
7
+ # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
8
+ def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
9
9
 
10
- # : (untyped, RootVersionPlan) -> Analysis
11
- def call: (untyped, RootVersionPlan) -> Analysis
10
+ # `window` is the root's window as the batch moved it to transaction edges.
11
+ # : (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
12
+ def call: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
12
13
 
13
14
  private
14
15
 
@@ -16,19 +17,17 @@ module PaperTrailDiff
16
17
 
17
18
  @activity_snapshotter: untyped
18
19
 
19
- @group: Symbol?
20
-
21
20
  @preparer: untyped
22
21
 
23
- @snapshots: bool
24
-
25
22
  @timeline_snapshotter: untyped
26
23
 
27
24
  @tree: AssociationTree
28
25
 
26
+ @view: ActivityView
27
+
29
28
  @within: untyped
30
29
 
31
- # : (untyped, RootVersionPlan) -> Analysis
32
- def activity_analysis: (untyped, RootVersionPlan) -> Analysis
30
+ # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
31
+ def activity_analysis: (untyped, RootVersionPlan, TimeRange?) -> Analysis
33
32
  end
34
33
  end
@@ -5,8 +5,8 @@ module PaperTrailDiff
5
5
  # queries. Only the range forms that mean the same thing for every root are
6
6
  # supported: a shared wall-clock window, or each root's own whole history.
7
7
  class BatchedRootVersions
8
- # : (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
9
- def initialize: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
8
+ # : (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
9
+ def initialize: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
10
10
 
11
11
  # Returns a plan per record identity.
12
12
  # : () -> Hash[Array[String], RootVersionPlan]
@@ -24,14 +24,24 @@ module PaperTrailDiff
24
24
 
25
25
  @version_scope: untyped
26
26
 
27
+ @windows: Hash[Array[String], TimeRange]
28
+
27
29
  # : (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
28
30
  def select_model: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
29
31
 
32
+ # Moved windows only start and end earlier, so the versions read for the
33
+ # widest of them hold each root's own, and the first left past a moved end.
34
+ # : (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
35
+ def own_window: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [ Array[untyped], untyped ]
36
+
30
37
  # : (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
31
38
  def model_versions: (untyped, Array[untyped]) -> [ Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped] ]
32
39
 
33
- # : (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
34
- def versions_for: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
40
+ # : (Array[untyped]) -> TimeRange?
41
+ def widest_range: (Array[untyped]) -> TimeRange?
42
+
43
+ # : (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
44
+ def versions_for: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
35
45
 
36
46
  # The batch already loaded every root, so closing on current state reuses
37
47
  # that rather than reading each record again.
@@ -54,11 +64,5 @@ module PaperTrailDiff
54
64
 
55
65
  # : (untyped, Array[untyped]) -> untyped
56
66
  def base_scope: (untyped, Array[untyped]) -> untyped
57
-
58
- # : (untyped) -> Array[untyped]
59
- def ordered: (untyped) -> Array[untyped]
60
-
61
- # : (untyped, untyped) -> Array[String]
62
- def identity: (untyped, untyped) -> Array[String]
63
67
  end
64
68
  end
@@ -0,0 +1,86 @@
1
+ # Generated from lib/paper_trail_diff/change_row.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # One change from an activity step, flat enough for a history table or an
5
+ # export: a field that changed, or a record that appeared or disappeared,
6
+ # with the event the step attributes it to.
7
+ class ChangeRow
8
+ attr_reader change: Symbol
9
+
10
+ attr_reader association_path: Array[String]
11
+
12
+ attr_reader association_kind: Symbol?
13
+
14
+ # The record the row is about, or nil for the root itself.
15
+ attr_reader record: RecordReference?
16
+
17
+ # The field the row is about, or nil for a row about a whole record.
18
+ attr_reader attribute: String?
19
+
20
+ attr_reader from: untyped
21
+
22
+ attr_reader to: untyped
23
+
24
+ # The step's source boundary: for a transaction group, its first event.
25
+ attr_reader source: ActivityBoundary
26
+
27
+ # : (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
28
+ def initialize: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
29
+
30
+ # The source's identifying fields sit beside the change rather than nested,
31
+ # so the hash is one row of a table as it stands.
32
+ # : () -> Hash[Symbol, untyped]
33
+ def to_h: () -> Hash[Symbol, untyped]
34
+
35
+ private
36
+
37
+ # : () -> Hash[Symbol, untyped]
38
+ def source_fields: () -> Hash[Symbol, untyped]
39
+ end
40
+
41
+ # Flattens one step's diff into change rows, in the diff's walking order.
42
+ #
43
+ # A row is about one record. An edited field is `:changed`. A record that
44
+ # appeared or disappeared is one `:added` or `:removed` row, followed by a
45
+ # row for each of its fields and for each record it holds, so a table can
46
+ # list a new comment's body without a second walker. That covers a record
47
+ # joining or leaving a collection, a to-one target set, cleared or replaced
48
+ # (the old target removed, then the new one added), and the root's own
49
+ # creation or deletion.
50
+ #
51
+ # Two kinds of entry add nothing a row would show. One that only groups
52
+ # others (an edited record, an association, a relationship) is left out,
53
+ # because the rows under it name the same record. A blank field of an added
54
+ # or removed record is left out too, because the record's own row already
55
+ # says it appeared or disappeared.
56
+ class ChangeRows
57
+ RECORD_ENTRIES: untyped
58
+
59
+ # : (Diff, source: ActivityBoundary) -> Array[ChangeRow]
60
+ def self.call: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
61
+
62
+ # : (ActivityBoundary) -> void
63
+ def initialize: (ActivityBoundary) -> void
64
+
65
+ # : (Diff) -> Array[ChangeRow]
66
+ def call: (Diff) -> Array[ChangeRow]
67
+
68
+ private
69
+
70
+ @source: ActivityBoundary
71
+
72
+ # : (TraversalEntry) -> ChangeRow?
73
+ def row_for: (TraversalEntry) -> ChangeRow?
74
+
75
+ # : (TraversalEntry) -> ChangeRow
76
+ def changed_row: (TraversalEntry) -> ChangeRow
77
+
78
+ # An added record's state is the after side and a removed one's the before
79
+ # side, so a field's value goes on the side that has it.
80
+ # : (TraversalEntry, String?) -> ChangeRow
81
+ def presence_row: (TraversalEntry, String?) -> ChangeRow
82
+
83
+ # : (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
84
+ def row: (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
85
+ end
86
+ end
@@ -2,6 +2,8 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Compares collection snapshots with a low-allocation path for stable membership.
5
+ # Snapshots hold their records in type and ID order, so results follow it
6
+ # without sorting here.
5
7
  class CollectionComparator
6
8
  # : (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
7
9
  def initialize: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
@@ -47,22 +49,6 @@ module PaperTrailDiff
47
49
  # : (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
48
50
  def index_records: (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
49
51
 
50
- # : (Array[identity]) -> Array[identity]
51
- def sorted_identities: (Array[identity]) -> Array[identity]
52
-
53
- # Identities sort by type first so that mixed id types stay comparable, then
54
- # naturally within one type. Ordering by the printed form instead would put
55
- # id 10 before id 2, which is deterministic but reads as unsorted wherever a
56
- # result is rendered.
57
- # : (identity) -> Array[untyped]
58
- def sortable_identity: (identity) -> Array[untyped]
59
-
60
- # Only the order of the group numbers matters, so moving the lowest one
61
- # down or the highest one up changes nothing; the spec checks the order.
62
- # mutant:disable
63
- # : (untyped) -> Array[untyped]
64
- def sortable_id: (untyped) -> Array[untyped]
65
-
66
52
  # : (identity) -> void
67
53
  def raise_duplicate_identity!: (identity) -> void
68
54
  end
@@ -3,8 +3,11 @@
3
3
  module PaperTrailDiff
4
4
  # Validates and executes independent comparisons with shared live endpoint loading.
5
5
  class ComparisonBatch
6
- # : (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
7
- def initialize: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
6
+ # `history_preparer` prepares roots that have a live endpoint to collect a
7
+ # graph from; `version_history_preparer` prepares roots compared only
8
+ # between versions.
9
+ # : (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, version_history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
10
+ def initialize: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, version_history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
8
11
 
9
12
  # : () -> comparison_results
10
13
  def call: () -> comparison_results
@@ -23,6 +26,8 @@ module PaperTrailDiff
23
26
 
24
27
  @preparer: untyped
25
28
 
29
+ @version_history_preparer: untyped
30
+
26
31
  # : (Array[[untyped, untyped]]) -> Hash[identity, RecordSnapshot]
27
32
  def prepared_live_snapshots: (Array[[ untyped, untyped ]]) -> Hash[identity, RecordSnapshot]
28
33
 
@@ -53,8 +58,21 @@ module PaperTrailDiff
53
58
  # : (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
54
59
  def prepare_historical_batches!: (Array[[ untyped, untyped ]], Hash[identity, untyped]) -> void
55
60
 
56
- # : (Array[[untyped, untyped]], Hash[identity, untyped]) -> Array[untyped]
57
- def historical_versions: (Array[[ untyped, untyped ]], Hash[identity, untyped]) -> Array[untyped]
61
+ # A root compared only between versions has no live endpoint, and its row
62
+ # may be gone. Without prepared history, PT-AT finds a has_many's children
63
+ # by the keys each version recorded after its change, so it misses a child
64
+ # that later moved to another owner. Such roots are prepared from identity
65
+ # alone, like deleted ones. Their history still reads the live rows it
66
+ # needs: a record's current row is its state after its last version.
67
+ # : (Array[untyped]) -> void
68
+ def prepare_version_roots!: (Array[untyped]) -> void
69
+
70
+ # The record supplies identity and model metadata only.
71
+ # : (untyped, untyped) -> untyped
72
+ def historical_root: (untyped, untyped) -> untyped
73
+
74
+ # : (Array[[untyped, untyped]]) -> Array[untyped]
75
+ def historical_versions: (Array[[ untyped, untyped ]]) -> Array[untyped]
58
76
 
59
77
  # : () -> Array[[untyped, untyped]]
60
78
  def comparison_pairs: () -> Array[[ untyped, untyped ]]
@@ -5,18 +5,27 @@ module PaperTrailDiff
5
5
  class AssociationTree
6
6
  attr_reader children: Hash[String, AssociationTree]
7
7
 
8
+ # Takes what `includes` takes: a name, a dotted path, a hash of names to
9
+ # what to include below them, or an array of any of these.
8
10
  # : (untyped) -> AssociationTree
9
11
  def self.build: (untyped) -> AssociationTree
10
12
 
13
+ # : (untyped, String?) -> Array[String]
14
+ private def self.paths: (untyped, String?) -> Array[String]
15
+
16
+ # `{ comments: :replies }` names comments as well as their replies.
17
+ # : (untyped, untyped, String?) -> Array[String]
18
+ private def self.nested_paths: (untyped, untyped, String?) -> Array[String]
19
+
20
+ # : (String?, String | Symbol) -> String
21
+ private def self.joined: (String?, String | Symbol) -> String
22
+
11
23
  # : (Hash[String, untyped], String) -> void
12
24
  private def self.add_path: (Hash[String, untyped], String) -> void
13
25
 
14
26
  # : (Hash[String, untyped]) -> AssociationTree
15
27
  private def self.from_hash: (Hash[String, untyped]) -> AssociationTree
16
28
 
17
- # : (untyped) -> bool
18
- private def self.valid_values?: (untyped) -> bool
19
-
20
29
  # : (Hash[String, AssociationTree]) -> void
21
30
  def initialize: (Hash[String, AssociationTree]) -> void
22
31
 
@@ -63,5 +72,12 @@ module PaperTrailDiff
63
72
 
64
73
  # : (String) -> Array[String]
65
74
  def attributes_for: (String) -> Array[String]
75
+
76
+ # The names to leave out of what a version recorded. A root version is
77
+ # known to be the root's, so its own path's names apply; any other version
78
+ # does not say which path reached it, so only the names ignored everywhere
79
+ # do.
80
+ # : (root: bool) -> Array[String]
81
+ def recorded_attributes: (root: bool) -> Array[String]
66
82
  end
67
83
  end