paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
data/docs/testing.md CHANGED
@@ -8,7 +8,7 @@ mise exec -- bundle exec rake
8
8
  ```
9
9
 
10
10
  The default task runs the core specs without PT-AT loaded, the association specs
11
- in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
11
+ and the [oracle checks](#oracle-checks) each in a separate process, RuboCop (with the rubocop-performance and rubocop-rspec
12
12
  plugins), generated-signature verification, and Steep.
13
13
  Ruby blocks in the README, quickstart, and API reference marked with
14
14
  `<!-- executable:... -->` run inside those specs, so documented examples stay
@@ -37,6 +37,69 @@ history, with integer and string `versions.item_id`, YAML and JSON history, and
37
37
  a `has_paper_trail skip:` column. When one fails, its seed reproduces it. Add a
38
38
  variant here when a bug turns out to depend on a schema or configuration.
39
39
 
40
+ ## Oracle checks
41
+
42
+ The consistency checks compare gem methods with each other, so a bug they
43
+ share passes. `spec/oracle` compares them with the truth instead:
44
+
45
+ 1. A seeded generator (`spec/support/oracle.rb`) makes random edits to an
46
+ article graph, one transaction each: root edits and checkpoints, comments
47
+ and replies created, edited, moved, and deleted, an author, a profile, and
48
+ authorships with their authors. Some transactions write several versions.
49
+ 2. After each transaction it records the live state, keyed by the versions
50
+ that transaction wrote, so every version names the state just before it.
51
+ The state comes from the gem's current-record path, which is plain Active
52
+ Record, and is checked against an independent read of each association.
53
+ 3. Every endpoint pair, every timeline step, every activity step (grouped and
54
+ not), and windows through `analyze`, `analyze_many`, and `analyze_scope`
55
+ are compared with the recorded states. Two windows that meet between
56
+ transactions, or inside one, must report each step once, as the window
57
+ spanning both does, through both `activity_timeline` and `analyze_many`.
58
+
59
+ Four more generators cover other shapes. `scoped_membership_spec.rb` moves
60
+ notes in and out of scoped associations (conditions, order, limit, and
61
+ offset) and compares the members at every version with Active Record's own
62
+ answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
63
+ inside another root's tree, with children whose attributes are encrypted,
64
+ serialized, enums stored as strings, custom types, decimals, and JSON.
65
+ `through_history_spec.rb` edits two teams' join records and the records they
66
+ reach, through every kind of `has_many :through`: to a `belongs_to`, through a
67
+ scoped part, ranked with a limit, to a `has_many`, through another through, a
68
+ `has_one` through, and with `source_type:`. `habtm_history_spec.rb` attaches,
69
+ detaches, creates, renames, and destroys tags between checkpoints. HABTM
70
+ membership is known only at root versions, so it expects what the
71
+ [reference](reference.md#habtm-limitation) describes: at each point, the
72
+ members the next root version recorded, as each was then, and only once it
73
+ exists. These three read the expected states with plain Active Record, not
74
+ through the gem.
75
+
76
+ `replay_differential_spec.rb` checks activity against the gem's own full
77
+ snapshots instead. Activity carries each snapshot forward from the previous
78
+ event, reading again only what the event changed; this replays generated
79
+ histories that way and with a full snapshot at every event, and fails on any
80
+ difference. Needing no expected states, it covers what the others avoid:
81
+ `has_paper_trail only:` and `ignore:` that leave keys out of `object_changes`,
82
+ and keys written by `update_columns` or with versioning off.
83
+ Mutant cannot check that carrying forward: a mutation that turns it off
84
+ falls back to a full snapshot, which gives the same answers, more slowly. This
85
+ check is what catches one that gives a different answer.
86
+
87
+ ```console
88
+ mise exec -- bundle exec rake spec_oracle
89
+ ORACLE_SEEDS=1..200 ORACLE_STEPS=40 mise exec -- bundle exec rake spec_oracle
90
+ ```
91
+
92
+ The default seeds keep the run to a few seconds; `rake spec` includes it, so
93
+ the database jobs run it too. Mutant does not, because it would slow every
94
+ mutation. A failure prints its seed and the transactions it made. To fix one,
95
+ reproduce it with that seed, reduce it to the few edits that matter, and add
96
+ that as a named spec beside the code it covers, so the cause is readable
97
+ without the generator.
98
+
99
+ When a bug turns out to depend on a schema, configuration, or kind of edit,
100
+ add it to the generator or as a new context, so the whole class of bug stays
101
+ covered.
102
+
40
103
  ## Mutation testing
41
104
 
42
105
  [Mutant](https://github.com/mbj/mutant) changes the library one expression at
@@ -51,8 +114,10 @@ passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
51
114
  - which versions a batch or filter reads: `BatchedRootVersions`,
52
115
  `DeletedAnalysisBatch`, and `HistoricalFilter`;
53
116
  - what a version recorded: `RecordedChanges`;
117
+ - how a step flattens into rows: `ChangeRow` and `ChangeRows`;
54
118
  - which records a scope or report selects: `ScopedRootSelection`,
55
- `AssociationActivitySelection`, and `AssociationActivityEdge`;
119
+ `AssociationActivitySelection`, `AssociationActivityEdge`, and
120
+ `DeletedRootFilter`;
56
121
  - which children and targets a record had at each point:
57
122
  `PreparedHistoryLoader`, `PreparedEdgeLoader`,
58
123
  `ActivityTargetCandidateLoader`, and `PreparedActivityIndex`;
@@ -60,10 +125,11 @@ passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
60
125
  query reads: `ActivityRange` and `VersionAssociationCandidateScope`;
61
126
  - what activity a record shows: `ActivityTimelineBuilder` and
62
127
  `ActivityTransactionGrouper`;
63
- - which association paths a request accepts: `AssociationTraversal`;
128
+ - which association paths a request accepts: `AssociationTraversal` and
129
+ `AssociationKey`;
64
130
  - whether a transaction's HABTM members are one record's:
65
131
  `HabtmTransactionOwners`;
66
- - which association paths a batch refuses: `BatchSafety`;
132
+ - which association paths history cannot read exactly: `ApproximatePaths`;
67
133
  - which records an association scope admits, and how it ranks them:
68
134
  `ScopeCondition` and `ScopeRanking`.
69
135
 
@@ -79,7 +145,10 @@ description names the mutated class (`RSpec.describe PaperTrailDiff::Engine`),
79
145
  falling back to wider names such as `PaperTrailDiff` when none does. A spec
80
146
  named after a behavior, as most integration specs are, never runs. So each
81
147
  mutated class has a unit spec of its own that catches every mutation in it,
82
- and a class added to `mutant.yml` needs one too.
148
+ and a class added to `mutant.yml` needs one too. A spec named after a
149
+ behavior can still name the class it checks with metadata, as the activity
150
+ window specs do: `RSpec.describe 'Activity over a window', mutant_expression:
151
+ 'PaperTrailDiff::ActivityTimelineBuilder'`.
83
152
 
84
153
  Mutant counts a mutation that runs past its time limit as caught, so
85
154
  `mutant.yml` sets the limit well above the time the whole suite takes. With
@@ -122,8 +191,10 @@ they resynchronize, which made window-based specs fail at random.
122
191
  `spec/support/monotonic_clock.rb` therefore makes `Time.now` strictly
123
192
  increasing, in whole microseconds, for the test process. ActiveRecord
124
193
  timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
125
- read it, so they stay consistent however the host clock moves. It affects only
126
- the test process; the gem itself reads the ordinary clock.
194
+ read it, so they stay consistent however the host clock moves. The benchmark
195
+ workload, `benchmark/support/workload.rb`, loads it too, because a step back
196
+ could date a root's destroy before its last update. It affects only the specs
197
+ and the benchmark; the gem itself reads the ordinary clock.
127
198
 
128
199
  ## Other databases locally
129
200
 
@@ -158,6 +229,11 @@ PaperTrail's default YAML serializer, the fixtures explicitly permit
158
229
  `ActiveRecord.yaml_column_permitted_classes` configuration. The gem does not
159
230
  change an application's YAML configuration.
160
231
 
232
+ PT-AT compares version times through SQL text, which SQL Server's adapter
233
+ writes as `datetime` values, up to 1/300 s off. So on SQL Server the
234
+ association specs keep their versions 5 ms apart, or the specs that compare
235
+ the gem with PT-AT would fail whenever versions were saved closer together.
236
+
161
237
  The CI service configuration is in `.github/workflows/ci.yml`. PostgreSQL and
162
238
  MySQL create the named database during container initialization. The SQL Server
163
239
  jobs create it explicitly after the service passes its health check.
@@ -17,9 +17,20 @@ module PaperTrailDiff
17
17
  # report one save as one step rather than as its parts.
18
18
  attr_reader :transaction_id #: untyped
19
19
 
20
+ # @rbs @recorded_changes: untyped
21
+
22
+ # Stands for recorded changes nobody asked to read, which differs from a
23
+ # version that recorded nothing (nil).
24
+ NOT_READ = Object.new.freeze
25
+ NOT_READ_MESSAGE = 'recorded changes were not read; pass recorded_changes: true'
26
+ private_constant :NOT_READ, :NOT_READ_MESSAGE
27
+
20
28
  class << self
21
- #: (untyped) -> ActivityBoundary
22
- def from_version(version)
29
+ # `recorded:` names the attributes to leave out of the version's recorded
30
+ # changes, or is nil when they were not asked for. Reading them decodes
31
+ # `object_changes`, which a caller who does not want them should not pay.
32
+ #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
33
+ def from_version(version, recorded: nil)
23
34
  new(
24
35
  kind: :version,
25
36
  version_id: version.id,
@@ -28,26 +39,29 @@ module PaperTrailDiff
28
39
  recorded_at: version.created_at,
29
40
  event: version.event,
30
41
  whodunnit: version.whodunnit,
31
- transaction_id: transaction_id(version)
42
+ transaction_id: VersionBoundary.transaction_id(version),
43
+ recorded_changes: recorded_changes(version, recorded)
32
44
  )
33
45
  end
34
46
 
35
- #: (untyped, captured_at: untyped) -> ActivityBoundary
36
- def current(record, captured_at:)
47
+ # The current record has no version, so it recorded nothing.
48
+ #: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
49
+ def current(record, captured_at:, recorded: nil)
37
50
  new(
38
51
  kind: :current,
39
52
  version_id: nil,
40
53
  item_type: record.class.base_class.name,
41
54
  item_id: record.id,
42
- recorded_at: captured_at
55
+ recorded_at: captured_at,
56
+ recorded_changes: recorded.nil? ? NOT_READ : nil
43
57
  )
44
58
  end
45
59
 
46
60
  # The state a `destroy` version leaves behind. A version records the state
47
61
  # before its own event, so the boundary built from a destroy version still
48
62
  # holds the record; this one is the absence that follows it.
49
- #: (untyped) -> ActivityBoundary
50
- def destroyed(version)
63
+ #: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
64
+ def destroyed(version, recorded: nil)
51
65
  new(
52
66
  kind: :destroyed,
53
67
  version_id: version.id,
@@ -56,20 +70,24 @@ module PaperTrailDiff
56
70
  recorded_at: version.created_at,
57
71
  event: version.event,
58
72
  whodunnit: version.whodunnit,
59
- transaction_id: transaction_id(version)
73
+ transaction_id: VersionBoundary.transaction_id(version),
74
+ recorded_changes: recorded_changes(version, recorded)
60
75
  )
61
76
  end
62
77
 
63
- # A custom version class need not carry the column, and PaperTrail leaves
64
- # it nil outside a transaction. Both read as "no transaction here", which
65
- # groups with nothing.
66
- #: (untyped) -> untyped
67
- def transaction_id(version)
68
- version.transaction_id if version.respond_to?(:transaction_id)
78
+ private
79
+
80
+ #: (untyped, Array[String]?) -> untyped
81
+ def recorded_changes(version, ignore)
82
+ return NOT_READ if ignore.nil?
83
+
84
+ RecordedChanges.call(version, ignore: ignore)
69
85
  end
70
86
  end
71
87
 
72
- #: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped) -> void
88
+ # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
89
+ # for the version; leave it out when they were not read.
90
+ #: (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
73
91
  def initialize( # rubocop:disable Metrics/ParameterLists
74
92
  kind:,
75
93
  version_id:,
@@ -78,7 +96,8 @@ module PaperTrailDiff
78
96
  recorded_at:,
79
97
  event: nil,
80
98
  whodunnit: nil,
81
- transaction_id: nil
99
+ transaction_id: nil,
100
+ recorded_changes: NOT_READ
82
101
  )
83
102
  @kind = kind
84
103
  @version_id = Support.immutable_copy(version_id)
@@ -88,10 +107,29 @@ module PaperTrailDiff
88
107
  @event = Support.immutable_copy(event&.to_s)
89
108
  @whodunnit = Support.immutable_copy(whodunnit)
90
109
  @transaction_id = Support.immutable_copy(transaction_id)
110
+ @recorded_changes = recorded_changes
91
111
  @record = RecordReference.new(type: @item_type, id: @item_id)
92
112
  freeze
93
113
  end
94
114
 
115
+ # What PaperTrail recorded with this boundary's version, as
116
+ # `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
117
+ # recorded, and always nil for the current record, which has no version.
118
+ # Raises unless the timeline was built with `recorded_changes: true`, so a
119
+ # forgotten option cannot pass for a version that recorded nothing.
120
+ #: () -> Hash[String, ValueChange]?
121
+ def recorded_changes
122
+ raise ConfigurationError, NOT_READ_MESSAGE unless recorded_changes?
123
+
124
+ @recorded_changes
125
+ end
126
+
127
+ # Whether this boundary's recorded changes were read.
128
+ #: () -> bool
129
+ def recorded_changes?
130
+ !NOT_READ.equal?(@recorded_changes)
131
+ end
132
+
95
133
  #: () -> bool
96
134
  def version?
97
135
  kind == :version
@@ -115,11 +153,14 @@ module PaperTrailDiff
115
153
  item_type: item_type,
116
154
  item_id: item_id,
117
155
  recorded_at: recorded_at
118
- }
156
+ } #: Hash[Symbol, untyped]
119
157
  return value unless metadata
120
158
 
121
- value.merge(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
122
- record: record.to_h)
159
+ value.merge!(event: event, whodunnit: whodunnit, transaction_id: transaction_id,
160
+ record: record.to_h)
161
+ return value unless recorded_changes?
162
+
163
+ value.merge(recorded_changes: @recorded_changes&.transform_values(&:to_h))
123
164
  end
124
165
  end
125
166
 
@@ -135,28 +176,35 @@ module PaperTrailDiff
135
176
  # get wrong.
136
177
  attr_reader :from_snapshot #: RecordSnapshot?
137
178
  attr_reader :to_snapshot #: RecordSnapshot?
179
+ # The events whose changes this step reports, in the order they happened.
180
+ # That is `source_boundary` alone, unless the step is a transaction group,
181
+ # which holds every event in it: an attribution that names only the first
182
+ # would credit the rest of the save to whoever opened it.
183
+ attr_reader :sources #: Array[ActivityBoundary]
138
184
 
139
185
  # Compares two reconstructed states and keeps them only when asked, which is
140
186
  # every caller's shape: the diff always comes from the pair, the pair itself
141
187
  # is retained on request.
142
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
143
- def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:)
188
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
189
+ def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
144
190
  new(
145
191
  from_boundary: from_boundary,
146
192
  to_boundary: to_boundary,
147
193
  diff: Engine.compare(from_snapshot, to_snapshot),
148
194
  from_snapshot: (from_snapshot if retain),
149
- to_snapshot: (to_snapshot if retain)
195
+ to_snapshot: (to_snapshot if retain),
196
+ sources: sources
150
197
  )
151
198
  end
152
199
 
153
- #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
154
- def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil)
200
+ #: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
201
+ def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
155
202
  @from_boundary = from_boundary
156
203
  @to_boundary = to_boundary
157
204
  @diff = diff
158
205
  @from_snapshot = from_snapshot
159
206
  @to_snapshot = to_snapshot
207
+ @sources = (sources || [from_boundary]).dup.freeze
160
208
  freeze
161
209
  end
162
210
 
@@ -170,13 +218,22 @@ module PaperTrailDiff
170
218
  #: () -> ActivityBoundary
171
219
  def source_boundary = from_boundary
172
220
 
221
+ # The diff as flat rows, each attributed to `source_boundary`.
222
+ #: () -> Array[ChangeRow]
223
+ def change_rows
224
+ ChangeRows.call(diff, source: source_boundary)
225
+ end
226
+
227
+ # `metadata: true` also lists `sources`, since who made a change is
228
+ # metadata as much as the source boundary's own author is.
173
229
  #: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
174
230
  def to_h(metadata: false, snapshots: false)
175
231
  value = {
176
232
  from: from_boundary.to_h(metadata: metadata),
177
233
  to: to_boundary.to_h(metadata: metadata),
178
234
  diff: diff.to_h
179
- }
235
+ } #: Hash[Symbol, untyped]
236
+ value[:sources] = sources.map { |source| source.to_h(metadata: true) } if metadata
180
237
  return value unless snapshots
181
238
 
182
239
  value.merge(from_snapshot: from_snapshot&.to_h, to_snapshot: to_snapshot&.to_h)
@@ -62,7 +62,8 @@ module PaperTrailDiff
62
62
 
63
63
  #: (untyped) -> untyped
64
64
  def historical_relation(version_class)
65
- @parent_class.paper_trail.version_association_class.joins(:version).where(
65
+ associations = @parent_class.paper_trail.version_association_class
66
+ VersionTable.joined(associations, version_class).where(
66
67
  foreign_key_name: @reflection.foreign_key.to_s,
67
68
  foreign_key_id: @parent_ids,
68
69
  foreign_type: parent_types
@@ -16,7 +16,8 @@ module PaperTrailDiff
16
16
  def safe?(routes, version, delta)
17
17
  !scoped_route?(routes) &&
18
18
  !unsafe_through_membership_event?(routes, version) &&
19
- !unsafe_nested_membership_delta?(routes, delta)
19
+ !unsafe_nested_membership_delta?(routes, delta) &&
20
+ !unsafe_owned_relationship_delta?(routes, delta)
20
21
  end
21
22
 
22
23
  #: (untyped, untyped, RecordSnapshot, SnapshotNormalizer, Array[Array[untyped]], untyped, ActivitySnapshotDelta?) -> [bool, RecordSnapshot]
@@ -92,6 +93,37 @@ module PaperTrailDiff
92
93
  end
93
94
  end
94
95
 
96
+ # A delta replaces a record's attributes and keeps its associations, so an
97
+ # edit to a key one of them follows, such as a comment's `reviewer_id`
98
+ # under `comments.reviewer`, would leave the old target in place. The
99
+ # branch is read again instead.
100
+ #: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
101
+ def unsafe_owned_relationship_delta?(routes, delta)
102
+ return false unless delta
103
+
104
+ routes.any? do |route|
105
+ _name, reflection, subtree, = route.last
106
+ subtree.children.each_key.any? do |name|
107
+ owned_keys(reflection.klass.reflect_on_association(name)).any? do |key|
108
+ delta.before_value(key).to_s != delta.after_value(key).to_s
109
+ end
110
+ end
111
+ end
112
+ end
113
+
114
+ # The record's own columns that decide what an association of it holds: a
115
+ # belongs_to's key and type, or those of the belongs_to a through starts
116
+ # from. A has_one or has_many follows the record's primary key.
117
+ #: (untyped) -> Array[untyped]
118
+ def owned_keys(reflection)
119
+ return [] unless reflection
120
+ return owned_keys(reflection.through_reflection) if reflection.through_reflection?
121
+ return [] unless reflection.belongs_to?
122
+
123
+ keys = Array(reflection.foreign_key)
124
+ reflection.polymorphic? ? [*keys, reflection.foreign_type] : keys
125
+ end
126
+
95
127
  #: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [untyped, RecordSnapshot?]
96
128
  def route_event_state( # rubocop:disable Metrics/ParameterLists
97
129
  snapshot, route, version, delta, fallback_record, normalizer, endpoints, direct: false
@@ -7,10 +7,11 @@ module PaperTrailDiff
7
7
  attr_reader :version #: untyped
8
8
  attr_reader :branches #: Array[String]?
9
9
 
10
- #: (version: untyped, branches: Array[String]?) -> void
11
- def initialize(version:, branches:)
10
+ #: (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
+ def initialize(version:, branches:, join: false)
12
12
  @version = version
13
13
  @branches = branches ? branches.map(&:to_s).uniq.sort.freeze : nil
14
+ @join = join
14
15
  freeze
15
16
  end
16
17
 
@@ -18,6 +19,15 @@ module PaperTrailDiff
18
19
  def root?
19
20
  branches.nil?
20
21
  end
22
+
23
+ # Whether the version is of a through's join row, which links the root to
24
+ # a target without being one.
25
+ #: () -> bool
26
+ def join?
27
+ @join
28
+ end
29
+
30
+ # @rbs @join: bool
21
31
  end
22
32
 
23
33
  # Accumulates each version once while retaining every selected root branch.
@@ -26,14 +36,15 @@ module PaperTrailDiff
26
36
  @events = {} #: Hash[Array[untyped], Hash[Symbol, untyped]]
27
37
  end
28
38
 
29
- #: (Array[untyped], ?branch: String?) -> void
30
- def add(versions, branch: nil)
39
+ #: (Array[untyped], ?branch: String?, ?join: bool) -> void
40
+ def add(versions, branch: nil, join: false)
31
41
  versions.each do |version|
32
42
  key = [version.class.name, version.id]
33
43
  existing = @events[key]
34
44
  @events[key] = {
35
45
  version: version,
36
- branches: merged_branches(existing, branch)
46
+ branches: merged_branches(existing, branch),
47
+ join: join || existing&.fetch(:join) || false
37
48
  }
38
49
  end
39
50
  end
@@ -43,7 +54,8 @@ module PaperTrailDiff
43
54
  @events.values.map do |event|
44
55
  ActivityEvent.new(
45
56
  version: event.fetch(:version),
46
- branches: event.fetch(:branches)
57
+ branches: event.fetch(:branches),
58
+ join: event.fetch(:join)
47
59
  )
48
60
  end
49
61
  end
@@ -64,6 +76,28 @@ module PaperTrailDiff
64
76
 
65
77
  # Resolves the branch union that PT-AT exposes atomically for one transaction.
66
78
  class ActivityTransactionGroups
79
+ # A range ending at a version ends at the state before that version's
80
+ # transaction: PT-AT rebuilds its associations without the changes saved
81
+ # alongside it. A descendant version from that transaction, such as the
82
+ # child update behind a `touch: true` parent version, is therefore past the
83
+ # end. Kept, it would open a step whose change the closing state cannot
84
+ # show, and that change would be reported nowhere. A range ending at a time
85
+ # has no transaction to stop before.
86
+ #: (Array[ActivityEvent], untyped) -> Array[ActivityEvent]
87
+ def self.before_closing(events, range_end)
88
+ key = transaction_key(range_end)
89
+ return events unless key
90
+
91
+ events.reject { |event| !event.root? && transaction_key(event.version) == key }.freeze
92
+ end
93
+
94
+ # A version without a transaction shares one with nothing.
95
+ #: (untyped) -> Array[untyped]?
96
+ def self.transaction_key(version)
97
+ transaction_id = VersionBoundary.transaction_id(version)
98
+ [version.class.name, transaction_id] if transaction_id
99
+ end
100
+
67
101
  #: (Array[ActivityEvent]) -> void
68
102
  def initialize(events)
69
103
  groups = grouped_events(events)
@@ -119,10 +153,7 @@ module PaperTrailDiff
119
153
 
120
154
  #: (ActivityEvent) -> Array[untyped]?
121
155
  def transaction_key(event)
122
- version = event.version
123
- return unless version.respond_to?(:transaction_id) && version.transaction_id
124
-
125
- [version.class.name, version.transaction_id]
156
+ self.class.transaction_key(event.version)
126
157
  end
127
158
  end
128
159
  end
@@ -9,6 +9,7 @@ module PaperTrailDiff
9
9
  @traversal = traversal
10
10
  @collection_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
11
11
  @belongs_to_routes = {} #: Hash[Array[untyped], Array[Array[untyped]]]
12
+ @through_parts = {} #: Hash[Array[untyped], bool]
12
13
  end
13
14
 
14
15
  #: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
@@ -21,11 +22,41 @@ module PaperTrailDiff
21
22
  cached(@belongs_to_routes, model_class, tree, target_type, path, :belongs_to)
22
23
  end
23
24
 
25
+ # Whether a has_many through in the tree joins through, or reaches,
26
+ # records of the type. Its membership follows their keys, which a route
27
+ # to the record elsewhere in the tree does not update.
28
+ #: (untyped, AssociationTree, String) -> bool
29
+ def through_part?(model_class, tree, target_type)
30
+ key = [model_class, tree, target_type]
31
+ return @through_parts[key] if @through_parts.key?(key)
32
+
33
+ @through_parts[key] = through_part_below?(model_class, tree, target_type, '')
34
+ end
35
+
24
36
  private
25
37
 
26
38
  # @rbs @traversal: AssociationTraversal
27
39
  # @rbs @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
28
40
  # @rbs @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
41
+ # @rbs @through_parts: Hash[Array[untyped], bool]
42
+
43
+ #: (untyped, AssociationTree, String, String) -> bool
44
+ def through_part_below?(model_class, tree, target_type, path)
45
+ @traversal.reflections_for(model_class, tree, path: path).any? do |reflection|
46
+ next true if through_reaches?(reflection, target_type)
47
+
48
+ subtree = tree.child(reflection.name.to_s) #: AssociationTree
49
+ child_path = Support.association_path(path, reflection.name)
50
+ !reflection.polymorphic? && !subtree.empty? &&
51
+ through_part_below?(reflection.klass, subtree, target_type, child_path)
52
+ end
53
+ end
54
+
55
+ #: (untyped, String) -> bool
56
+ def through_reaches?(reflection, target_type)
57
+ reflection.through_reflection? &&
58
+ reflection.chain.any? { |part| part.klass.base_class.name.to_s == target_type }
59
+ end
29
60
 
30
61
  # Timelines interleave event types, so every requested combination is
31
62
  # retained. Model, tree, and path are fixed per adapter, leaving one entry
@@ -65,7 +65,7 @@ module PaperTrailDiff
65
65
  )
66
66
  unless routes.empty?
67
67
  delta = @record_resolver.snapshot_delta(event.version)
68
- return [false, nil] unless @collection_applier.safe?(routes, event.version, delta)
68
+ return [false, nil] unless collection_safe?(root_endpoint, tree, routes, event, delta)
69
69
 
70
70
  return @collection_applier.call(
71
71
  root_endpoint,
@@ -99,6 +99,17 @@ module PaperTrailDiff
99
99
 
100
100
  private :belongs_to_applier, :collection_applier, :collection_updater, :configure_appliers
101
101
 
102
+ # A through's membership follows the keys of the records it joins through
103
+ # or reaches, which a route to such a record elsewhere in the tree leaves
104
+ # alone, so the branch is read again instead.
105
+ #: (untyped, AssociationTree, Array[Array[untyped]], ActivityEvent, ActivitySnapshotDelta?) -> bool
106
+ def collection_safe?(root_endpoint, tree, routes, event, delta)
107
+ version = event.version
108
+ !@route_finder.through_part?(endpoint_model_class(root_endpoint), tree,
109
+ version.item_type.to_s) &&
110
+ @collection_applier.safe?(routes, version, delta)
111
+ end
112
+
102
113
  #: (untyped) -> untyped
103
114
  def record_after(version)
104
115
  @record_resolver.record_after(version, direct: true)