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
@@ -24,26 +24,49 @@ module PaperTrailDiff
24
24
  # report one save as one step rather than as its parts.
25
25
  attr_reader transaction_id: untyped
26
26
 
27
- # : (untyped) -> ActivityBoundary
28
- def self.from_version: (untyped) -> ActivityBoundary
27
+ @recorded_changes: untyped
29
28
 
30
- # : (untyped, captured_at: untyped) -> ActivityBoundary
31
- def self.current: (untyped, captured_at: untyped) -> ActivityBoundary
29
+ # Stands for recorded changes nobody asked to read, which differs from a
30
+ # version that recorded nothing (nil).
31
+ NOT_READ: untyped
32
+
33
+ NOT_READ_MESSAGE: ::String
34
+
35
+ # `recorded:` names the attributes to leave out of the version's recorded
36
+ # changes, or is nil when they were not asked for. Reading them decodes
37
+ # `object_changes`, which a caller who does not want them should not pay.
38
+ # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
39
+ def self.from_version: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
40
+
41
+ # The current record has no version, so it recorded nothing.
42
+ # : (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
43
+ def self.current: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
32
44
 
33
45
  # The state a `destroy` version leaves behind. A version records the state
34
46
  # before its own event, so the boundary built from a destroy version still
35
47
  # holds the record; this one is the absence that follows it.
36
- # : (untyped) -> ActivityBoundary
37
- def self.destroyed: (untyped) -> ActivityBoundary
38
-
39
- # A custom version class need not carry the column, and PaperTrail leaves
40
- # it nil outside a transaction. Both read as "no transaction here", which
41
- # groups with nothing.
42
- # : (untyped) -> untyped
43
- def self.transaction_id: (untyped) -> untyped
44
-
45
- # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
46
- def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
48
+ # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
49
+ def self.destroyed: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
50
+
51
+ # : (untyped, Array[String]?) -> untyped
52
+ private def self.recorded_changes: (untyped, Array[String]?) -> untyped
53
+
54
+ # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
55
+ # for the version; leave it out when they were not read.
56
+ # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
57
+ def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
58
+
59
+ # What PaperTrail recorded with this boundary's version, as
60
+ # `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
61
+ # recorded, and always nil for the current record, which has no version.
62
+ # Raises unless the timeline was built with `recorded_changes: true`, so a
63
+ # forgotten option cannot pass for a version that recorded nothing.
64
+ # : () -> Hash[String, ValueChange]?
65
+ def recorded_changes: () -> Hash[String, ValueChange]?
66
+
67
+ # Whether this boundary's recorded changes were read.
68
+ # : () -> bool
69
+ def recorded_changes?: () -> bool
47
70
 
48
71
  # : () -> bool
49
72
  def version?: () -> bool
@@ -75,14 +98,20 @@ module PaperTrailDiff
75
98
 
76
99
  attr_reader to_snapshot: RecordSnapshot?
77
100
 
101
+ # The events whose changes this step reports, in the order they happened.
102
+ # That is `source_boundary` alone, unless the step is a transaction group,
103
+ # which holds every event in it: an attribution that names only the first
104
+ # would credit the rest of the save to whoever opened it.
105
+ attr_reader sources: Array[ActivityBoundary]
106
+
78
107
  # Compares two reconstructed states and keeps them only when asked, which is
79
108
  # every caller's shape: the diff always comes from the pair, the pair itself
80
109
  # is retained on request.
81
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
82
- def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
110
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
111
+ def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
83
112
 
84
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
85
- def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
113
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
114
+ def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
86
115
 
87
116
  # : () -> bool
88
117
  def empty?: () -> bool
@@ -92,6 +121,12 @@ module PaperTrailDiff
92
121
  # : () -> ActivityBoundary
93
122
  def source_boundary: () -> ActivityBoundary
94
123
 
124
+ # The diff as flat rows, each attributed to `source_boundary`.
125
+ # : () -> Array[ChangeRow]
126
+ def change_rows: () -> Array[ChangeRow]
127
+
128
+ # `metadata: true` also lists `sources`, since who made a change is
129
+ # metadata as much as the source boundary's own author is.
95
130
  # : (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
96
131
  def to_h: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
97
132
  end
@@ -25,6 +25,11 @@ module PaperTrailDiff
25
25
  # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
26
26
  def apply_route: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> RecordSnapshot
27
27
 
28
+ # Any edit can move a record into or out of a scope, so a scoped route's
29
+ # branch is read again from history instead.
30
+ # : (Array[Array[untyped]]) -> bool
31
+ def scoped_route?: (Array[Array[untyped]]) -> bool
32
+
28
33
  # : (Array[Array[untyped]], untyped) -> bool
29
34
  def unsafe_through_membership_event?: (Array[Array[untyped]], untyped) -> bool
30
35
 
@@ -19,6 +19,11 @@ module PaperTrailDiff
19
19
 
20
20
  @relationship: ActivityRelationship
21
21
 
22
+ # A row whose STI type changed is the same row under a new identity, so it
23
+ # is found by id among the records of its table.
24
+ # : (AssociationSnapshot, untyped) -> Integer?
25
+ def retyped_position: (AssociationSnapshot, untyped) -> Integer?
26
+
22
27
  # : (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
23
28
  def replacement_records: (Array[RecordSnapshot], Integer?, RecordSnapshot?) -> Array[RecordSnapshot]
24
29
  end
@@ -7,19 +7,26 @@ module PaperTrailDiff
7
7
 
8
8
  attr_reader branches: Array[String]?
9
9
 
10
- # : (version: untyped, branches: Array[String]?) -> void
11
- def initialize: (version: untyped, branches: Array[String]?) -> void
10
+ # : (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
+ def initialize: (version: untyped, branches: Array[String]?, ?join: bool) -> void
12
12
 
13
13
  # : () -> bool
14
14
  def root?: () -> bool
15
+
16
+ # Whether the version is of a through's join row, which links the root to
17
+ # a target without being one.
18
+ # : () -> bool
19
+ def join?: () -> bool
20
+
21
+ @join: bool
15
22
  end
16
23
 
17
24
  # Accumulates each version once while retaining every selected root branch.
18
25
  class ActivityEventRegistry
19
26
  def initialize: () -> untyped
20
27
 
21
- # : (Array[untyped], ?branch: String?) -> void
22
- def add: (Array[untyped], ?branch: String?) -> void
28
+ # : (Array[untyped], ?branch: String?, ?join: bool) -> void
29
+ def add: (Array[untyped], ?branch: String?, ?join: bool) -> void
23
30
 
24
31
  # : () -> Array[ActivityEvent]
25
32
  def to_a: () -> Array[ActivityEvent]
@@ -34,6 +41,20 @@ module PaperTrailDiff
34
41
 
35
42
  # Resolves the branch union that PT-AT exposes atomically for one transaction.
36
43
  class ActivityTransactionGroups
44
+ # A range ending at a version ends at the state before that version's
45
+ # transaction: PT-AT rebuilds its associations without the changes saved
46
+ # alongside it. A descendant version from that transaction, such as the
47
+ # child update behind a `touch: true` parent version, is therefore past the
48
+ # end. Kept, it would open a step whose change the closing state cannot
49
+ # show, and that change would be reported nowhere. A range ending at a time
50
+ # has no transaction to stop before.
51
+ # : (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
52
+ def self.before_closing: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
53
+
54
+ # A version without a transaction shares one with nothing.
55
+ # : (untyped) -> Array[untyped]?
56
+ def self.transaction_key: (untyped) -> Array[untyped]?
57
+
37
58
  # : (Array[ActivityEvent]) -> void
38
59
  def initialize: (Array[ActivityEvent]) -> void
39
60
 
@@ -45,6 +45,13 @@ module PaperTrailDiff
45
45
  # : (untyped) -> PreparedRecordState?
46
46
  def direct_record_after: (untyped) -> PreparedRecordState?
47
47
 
48
+ # Without `item_subtype` a version names only the STI base class, and a
49
+ # change can move the row to another class, so the type the row holds
50
+ # after the change decides. A type that names no class has no direct
51
+ # state; the caller falls back to reifying the record.
52
+ # : (untyped, Hash[untyped, untyped]) -> untyped
53
+ def class_after: (untyped, Hash[untyped, untyped]) -> untyped
54
+
48
55
  # : (untyped) -> untyped
49
56
  def prepared_changeset: (untyped) -> untyped
50
57
 
@@ -24,14 +24,19 @@ module PaperTrailDiff
24
24
 
25
25
  # Builds activity steps while retaining root snapshots for combined analysis.
26
26
  class ActivityHistoryBuilder
27
- # : (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
28
- def initialize: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
27
+ # `closing` is the snapshot after the last event when the range closes on
28
+ # the current record. Any other range ends at a root event, or at events
29
+ # after a window whose steps are not reported, so nothing reads it.
30
+ # : (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
31
+ def initialize: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
29
32
 
30
33
  # : () -> ActivityHistory
31
34
  def call: () -> ActivityHistory
32
35
 
33
36
  private
34
37
 
38
+ @closing: RecordSnapshot?
39
+
35
40
  @current: untyped
36
41
 
37
42
  @events: Array[ActivityEvent]
@@ -40,6 +45,8 @@ module PaperTrailDiff
40
45
 
41
46
  @include_step: untyped
42
47
 
48
+ @passed_reported: bool
49
+
43
50
  @previous_boundary: ActivityBoundary?
44
51
 
45
52
  @previous_event: ActivityEvent?
@@ -52,20 +59,28 @@ module PaperTrailDiff
52
59
 
53
60
  @selected_last_snapshot: RecordSnapshot?
54
61
 
55
- @snapshots: bool
56
-
57
62
  @snapshotter: untyped
58
63
 
59
64
  @steps: Array[ActivityStep]
60
65
 
66
+ @view: ActivityView
67
+
61
68
  # : () -> void
62
69
  def reset: () -> void
63
70
 
71
+ # : () -> ActivityTreeFilter
72
+ def filter: () -> ActivityTreeFilter
73
+
64
74
  # : () -> ActivitySnapshotSequence
65
75
  def sequence: () -> ActivitySnapshotSequence
66
76
 
67
- # : (ActivityEvent, RecordSnapshot?) -> void
68
- def consume: (ActivityEvent, RecordSnapshot?) -> void
77
+ # A left-out event bounds nothing. A reported step it would have opened
78
+ # still moves the reported range's end past it, to the next boundary.
79
+ # : (ActivityEvent, RecordSnapshot?, bool) -> void
80
+ def consume: (ActivityEvent, RecordSnapshot?, bool) -> void
81
+
82
+ # : (ActivityEvent) -> void
83
+ def pass: (ActivityEvent) -> void
69
84
 
70
85
  # : (RecordSnapshot?) -> void
71
86
  def capture_first: (RecordSnapshot?) -> void
@@ -13,26 +13,37 @@ module PaperTrailDiff
13
13
  # : (untyped) -> bool
14
14
  def include?: (untyped) -> bool
15
15
 
16
- # Narrows an Active Record version relation by timestamp. Exact tie-breaking
17
- # remains in #include? so this works for integer, UUID, and custom version IDs.
16
+ # Narrows an Active Record version relation by timestamp, and to the
17
+ # start's transaction. Exact tie-breaking remains in #include? so this
18
+ # works for integer, UUID, and custom version IDs.
18
19
  # : (untyped) -> untyped
19
20
  def scope: (untyped) -> untyped
20
21
 
21
22
  # : () -> bool
22
23
  def current_end?: () -> bool
23
24
 
25
+ # Whether the state a version recorded after its change held inside the
26
+ # range. A range ending at a version ends at the state before it, so the
27
+ # change that version records is past the end, unlike #include?.
28
+ # : (untyped, untyped) -> bool
29
+ def recorded_before_end?: (untyped, untyped) -> bool
30
+
24
31
  private
25
32
 
26
33
  @end_boundary: untyped
27
34
 
28
35
  @end_key: Array[untyped]?
29
36
 
30
- @start_boundary: untyped
37
+ @opening_transaction: Array[untyped]?
31
38
 
32
39
  @start_key: Array[untyped]?
33
40
 
34
41
  @start_time: untyped
35
42
 
43
+ # A range starting at a version starts before that version's transaction,
44
+ # where PT-AT reads its associations. A version saved earlier in it, such
45
+ # as the child update behind a `touch: true` parent version, is a change
46
+ # inside the range.
36
47
  # : (untyped, Array[untyped]) -> bool
37
48
  def after_start?: (untyped, Array[untyped]) -> bool
38
49
 
@@ -11,6 +11,9 @@ module PaperTrailDiff
11
11
 
12
12
  private
13
13
 
14
+ # : (untyped, untyped, Symbol) -> bool
15
+ def sti_member?: (untyped, untyped, Symbol) -> bool
16
+
14
17
  # : (untyped, untyped, state: Symbol) -> Array[String]
15
18
  def relationship_owner_values: (untyped, untyped, state: Symbol) -> Array[String]
16
19
 
@@ -36,6 +36,8 @@ module PaperTrailDiff
36
36
  # : (untyped) -> Array[String]
37
37
  def unsupported_branches: (untyped) -> Array[String]
38
38
 
39
+ # A polymorphic target's class is known only per record, so it cannot be
40
+ # checked here; a target that is not versioned raises when it is read.
39
41
  # : (untyped) -> bool
40
42
  def direct_versioned_reflection?: (untyped) -> bool
41
43
 
@@ -1,13 +1,44 @@
1
1
  # Generated from lib/paper_trail_diff/activity_snapshot_sequence.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Optional full/partial snapshot operations consumed by the activity sequence.
4
+ # Prepares the snapshot store for an activity build, one root at a time.
5
+ # Before that, it reads the live record a range closes on.
5
6
  class ActivitySnapshotProvider
6
- # : (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
7
- def initialize: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
7
+ # `snapshotter` reads a full snapshot with a given history, and `refresher`
8
+ # builds the incremental refresher for one root's snapshots.
9
+ # : (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
10
+ def initialize: (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
11
+
12
+ # Roots a batch prepared together share its history, so consecutive ones
13
+ # share these snapshots too, and the caches their refresher builds. They
14
+ # are the same for any root with that history, so reusing them depends on
15
+ # nothing but the history.
16
+ # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
17
+ def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
8
18
 
9
- # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
10
- def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
19
+ # : (untyped, untyped) -> RecordSnapshot?
20
+ def call: (untyped, untyped) -> RecordSnapshot?
21
+
22
+ @last: PreparedActivitySnapshots?
23
+
24
+ @refresher: untyped
25
+
26
+ @snapshotter: untyped
27
+
28
+ @store: HistoricalSnapshotStore
29
+ end
30
+
31
+ # One root's full and incremental snapshots during an activity build. Each
32
+ # read passes along the history prepared for this root, so none depends on
33
+ # which root was prepared last.
34
+ class PreparedActivitySnapshots
35
+ attr_reader history: PreparedHistory?
36
+
37
+ # : (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
38
+ def initialize: (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
39
+
40
+ # : () -> PreparedActivityIndex?
41
+ def activity_index: () -> PreparedActivityIndex?
11
42
 
12
43
  # : (untyped, untyped) -> RecordSnapshot?
13
44
  def call: (untyped, untyped) -> RecordSnapshot?
@@ -18,16 +49,24 @@ module PaperTrailDiff
18
49
  # : (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
19
50
  def advance_root: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
20
51
 
21
- # : () -> PreparedActivityIndex?
22
- def activity_index: () -> PreparedActivityIndex?
52
+ # The branches a refresh rebuilds, with this root's history.
53
+ # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
54
+ def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
23
55
 
24
- @activity_index: untyped
56
+ # : (untyped, habtm_version: untyped) -> untyped
57
+ def association_reader: (untyped, habtm_version: untyped) -> untyped
25
58
 
26
- @preparer: untyped
59
+ # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
60
+ def record_transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
61
+
62
+ # : (untyped, ?direct: bool) -> [bool, untyped]
63
+ def record_after: (untyped, ?direct: bool) -> [ bool, untyped ]
27
64
 
28
65
  @refresher: untyped
29
66
 
30
67
  @snapshotter: untyped
68
+
69
+ @store: HistoricalSnapshotStore
31
70
  end
32
71
 
33
72
  # Builds chronological snapshots, refreshing only branches affected by prior events.
@@ -0,0 +1,79 @@
1
+ # Generated from lib/paper_trail_diff/activity_target_candidate_loader.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Loads the `belongs_to` targets owners pointed at during one activity range:
5
+ # at its start and after each change inside it.
6
+ #
7
+ # PT-AT records a version's foreign keys as they stood after its change, so
8
+ # the target at the start comes from the latest version before it, and the
9
+ # version a range ends at names a target only after the range. Reading only
10
+ # the owners' versions inside the range misses a target whose owner did not
11
+ # change there -- an author renamed under an article nobody edited.
12
+ class ActivityTargetCandidateLoader
13
+ # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
14
+ # gem supports 3.1.
15
+ class Row
16
+ attr_reader owner_id: untyped
17
+
18
+ attr_reader foreign_key_id: untyped
19
+
20
+ attr_reader foreign_type: String?
21
+
22
+ attr_reader created_at: untyped
23
+
24
+ attr_reader event: String?
25
+
26
+ attr_reader version_id: untyped
27
+
28
+ # : (untyped, untyped, String?, ?untyped, ?String?, ?untyped) -> void
29
+ def initialize: (untyped, untyped, String?, ?untyped, ?String?, ?untyped) -> void
30
+ end
31
+
32
+ # : (untyped, Array[untyped], untyped, ActivityRange) -> void
33
+ def initialize: (untyped, Array[untyped], untyped, ActivityRange) -> void
34
+
35
+ # : () -> Array[Row]
36
+ def call: () -> Array[Row]
37
+
38
+ # One shared query keeps the owner and timestamp needed to partition a
39
+ # batch's candidates back into each root's exact activity range.
40
+ # : () -> Array[Row]
41
+ def historical_rows: () -> Array[Row]
42
+
43
+ # The live row holds the state at a range that ends at the current record.
44
+ # : () -> Array[Row]
45
+ def current_rows: () -> Array[Row]
46
+
47
+ private
48
+
49
+ @owner_class: untyped
50
+
51
+ @owner_ids: Array[untyped]
52
+
53
+ @range: ActivityRange
54
+
55
+ @reflection: untyped
56
+
57
+ # : (untyped) -> untyped
58
+ def historical_relation: (untyped) -> untyped
59
+
60
+ # : (untyped, untyped) -> Array[Array[untyped]]
61
+ def historical_columns: (untyped, untyped) -> Array[Array[untyped]]
62
+
63
+ # A polymorphic key names its target in a type column; any other names it
64
+ # in the reflection, so no type is read. Like the history, the live read
65
+ # takes owners of every class under the base class: a batch can ask for
66
+ # the owners of an association through one subclass.
67
+ # : () -> Array[Array[untyped]]
68
+ def live_rows: () -> Array[Array[untyped]]
69
+
70
+ # : (untyped) -> VersionAssociationCandidateScope
71
+ def candidate_scope: (untyped) -> VersionAssociationCandidateScope
72
+
73
+ # : () -> untyped
74
+ def association_class: () -> untyped
75
+
76
+ # : () -> bool
77
+ def composite_foreign_key?: () -> bool
78
+ end
79
+ end