paper_trail_diff 0.16.0 → 0.17.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +566 -1
- data/README.md +42 -7
- data/docs/architecture.md +7 -5
- data/docs/performance.md +86 -38
- data/docs/reference.md +309 -92
- data/docs/testing.md +240 -32
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
- data/lib/paper_trail_diff/activity_boundary.rb +55 -34
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
- data/lib/paper_trail_diff/activity_event.rb +33 -21
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
- data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
- data/lib/paper_trail_diff/activity_history.rb +90 -49
- data/lib/paper_trail_diff/activity_range.rb +9 -35
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
- data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
- data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
- data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
- data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
- data/lib/paper_trail_diff/activity_view.rb +22 -11
- data/lib/paper_trail_diff/analysis.rb +19 -5
- data/lib/paper_trail_diff/analysis_batch.rb +16 -58
- data/lib/paper_trail_diff/approximate_paths.rb +4 -8
- data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
- data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
- data/lib/paper_trail_diff/association_discovery.rb +1 -6
- data/lib/paper_trail_diff/association_key.rb +9 -6
- data/lib/paper_trail_diff/association_traversal.rb +49 -6
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
- data/lib/paper_trail_diff/batch_preload.rb +2 -12
- data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
- data/lib/paper_trail_diff/change_attribution.rb +314 -0
- data/lib/paper_trail_diff/change_row.rb +30 -10
- data/lib/paper_trail_diff/comparison_batch.rb +3 -4
- data/lib/paper_trail_diff/configuration.rb +1 -1
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
- data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
- data/lib/paper_trail_diff/deprecation.rb +4 -43
- data/lib/paper_trail_diff/diagnostics.rb +1 -2
- data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
- data/lib/paper_trail_diff/endpoint.rb +78 -44
- data/lib/paper_trail_diff/errors.rb +2 -9
- data/lib/paper_trail_diff/fallback_paths.rb +2 -5
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
- data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
- data/lib/paper_trail_diff/historical_filter.rb +40 -15
- data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
- data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
- data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
- data/lib/paper_trail_diff/nested_comparator.rb +46 -19
- data/lib/paper_trail_diff/net_change.rb +276 -0
- data/lib/paper_trail_diff/own_window.rb +35 -0
- data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
- data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
- data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
- data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
- data/lib/paper_trail_diff/prepared_history.rb +20 -31
- data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
- data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
- data/lib/paper_trail_diff/read_snapshot.rb +41 -19
- data/lib/paper_trail_diff/recorded_changes.rb +10 -11
- data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
- data/lib/paper_trail_diff/recorded_class.rb +14 -19
- data/lib/paper_trail_diff/recorded_columns.rb +33 -0
- data/lib/paper_trail_diff/root_version_plan.rb +20 -22
- data/lib/paper_trail_diff/root_version_selection.rb +39 -29
- data/lib/paper_trail_diff/scope_condition.rb +7 -17
- data/lib/paper_trail_diff/scope_ranking.rb +16 -22
- data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
- data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
- data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
- data/lib/paper_trail_diff/stored_json_values.rb +52 -0
- data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
- data/lib/paper_trail_diff/stored_values.rb +20 -0
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +39 -0
- data/lib/paper_trail_diff/time_range.rb +37 -20
- data/lib/paper_trail_diff/time_version_range.rb +5 -10
- data/lib/paper_trail_diff/timeline_builder.rb +3 -3
- data/lib/paper_trail_diff/timeline_range.rb +18 -12
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
- data/lib/paper_trail_diff/total_order.rb +55 -0
- data/lib/paper_trail_diff/transaction_cut.rb +192 -91
- data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
- data/lib/paper_trail_diff/value_objects.rb +8 -4
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
- data/lib/paper_trail_diff/version_boundary.rb +37 -21
- data/lib/paper_trail_diff/version_query.rb +25 -25
- data/lib/paper_trail_diff/version_range.rb +12 -16
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
- data/lib/paper_trail_diff/version_table.rb +12 -8
- data/lib/paper_trail_diff.rb +28 -42
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
- data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
- data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
- data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
- data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
- data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
- data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
- data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
- data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
- data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
- data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
- data/sig/generated/paper_trail_diff/errors.rbs +2 -11
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
- data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
- data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
- data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
- data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
- data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
- data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
- data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
- data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
- data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
- data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
- data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
- data/sig/generated/paper_trail_diff/support.rbs +120 -23
- data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
- data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
- data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
- data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
- data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
- data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
- data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
- data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
- data/sig/generated/paper_trail_diff.rbs +16 -16
- metadata +28 -6
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
data/docs/testing.md
CHANGED
|
@@ -16,15 +16,41 @@ correct.
|
|
|
16
16
|
|
|
17
17
|
For reporting workloads, query counts, reconstruction cost, and memory readings,
|
|
18
18
|
see [Reporting performance](performance.md). Those measurements run separately
|
|
19
|
-
from the correctness suite and have no timing-based CI gate
|
|
19
|
+
from the correctness suite and have no timing-based CI gate; the
|
|
20
|
+
[SQL work](#sql-work) spec checks how a report's SQL grows instead.
|
|
20
21
|
|
|
21
22
|
CI keeps the Ruby 3.1–4.0 and PaperTrail 16/17 compatibility matrix on SQLite,
|
|
22
23
|
including Windows runs. Separate Linux jobs run both core and association suites
|
|
23
24
|
on PostgreSQL 17, MySQL 8.4, and SQL Server 2019 and 2022 with Ruby 4.0 and
|
|
24
|
-
PaperTrail 17.
|
|
25
|
+
PaperTrail 17. The SQL Server 2022 job's database allows snapshot isolation
|
|
26
|
+
and the 2019 job's does not, so each call's `SNAPSHOT` read is run both ways.
|
|
25
27
|
The SQL jobs exercise the same regressions, including joined-column ordering,
|
|
26
28
|
duplicate roots, pagination, and historical association reconstruction.
|
|
27
29
|
|
|
30
|
+
## JSON history
|
|
31
|
+
|
|
32
|
+
PaperTrail writes history with YAML unless an app sets its JSON serializer, so
|
|
33
|
+
the suites do too. To run them with JSON history instead:
|
|
34
|
+
|
|
35
|
+
```console
|
|
36
|
+
PAPER_TRAIL_DIFF_SERIALIZER=json mise exec -- bundle exec rake spec
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
A CI job runs them that way on Ruby 4.0 and PaperTrail 17. The PaperTrail 16
|
|
40
|
+
jobs run Active Support 8.0, whose JSON encoder passes a keyword
|
|
41
|
+
(`quirks_mode:`) that json 3 rejects, and the SQL Server adapter hands the
|
|
42
|
+
encoder a value it refuses, so nothing can be written as JSON there, and the
|
|
43
|
+
specs that switch to JSON themselves skip.
|
|
44
|
+
|
|
45
|
+
Write a fixture version with `PaperTrail.serializer.dump`, not `to_yaml`, so it
|
|
46
|
+
holds what either run's history would. An example about YAML history itself
|
|
47
|
+
is tagged `history: :yaml` and keeps YAML in both runs. JSON keeps times to
|
|
48
|
+
milliseconds by default, so an oracle's truth, read from live rows, cuts times
|
|
49
|
+
to the digits history keeps (`HistorySerializer.as_stored`), as the gem does
|
|
50
|
+
when it compares a live row with history. A scope that orders or bounds a
|
|
51
|
+
time more finely than that is refused under JSON, and the specs that read one
|
|
52
|
+
leave it out there.
|
|
53
|
+
|
|
28
54
|
## Consistency checks
|
|
29
55
|
|
|
30
56
|
`spec/association/consistency_spec.rb` and `spec/integration/consistency_spec.rb`
|
|
@@ -34,8 +60,24 @@ agrees: `analyze`, `analyze_many`, and `analyze_scope`; checkpoint and activity
|
|
|
34
60
|
modes; `compare` and `timeline` against `analyze`; and that activity steps
|
|
35
61
|
chain into the final state. They run over random windows as well as the whole
|
|
36
62
|
history, with integer and string `versions.item_id`, YAML and JSON history, and
|
|
37
|
-
a `has_paper_trail skip:` column. When one fails, its seed reproduces it
|
|
38
|
-
|
|
63
|
+
a `has_paper_trail skip:` column. When one fails, its seed reproduces it, and
|
|
64
|
+
`ORACLE_SHRINK=1` reduces it, as for the oracles (see
|
|
65
|
+
[Reducing a failure](#reducing-a-failure)). Add a variant here when a bug
|
|
66
|
+
turns out to depend on a schema or configuration.
|
|
67
|
+
|
|
68
|
+
## SQL work
|
|
69
|
+
|
|
70
|
+
A statement whose plan reads a report's window again for each of its roots'
|
|
71
|
+
versions passes every correctness check and shows only at scale.
|
|
72
|
+
`spec/association/report_sql_work_spec.rb` reports on articles with their
|
|
73
|
+
comments, with the README's indexes, since plans depend on them. It then adds
|
|
74
|
+
other records' history to the window and reports again. It runs each SELECT
|
|
75
|
+
again on its own and reads the steps SQLite's virtual machine took, which are
|
|
76
|
+
the same on every run for the same data and SQLite version. It fails when
|
|
77
|
+
each added version costs the report more than 100 steps: about 27 when it was
|
|
78
|
+
written, and about 380 with the correlated subquery that once took a report
|
|
79
|
+
of 10,000 articles from 6 to 44 ms an article. The failure lists the
|
|
80
|
+
statements that grew most. It runs on SQLite only.
|
|
39
81
|
|
|
40
82
|
## Oracle checks
|
|
41
83
|
|
|
@@ -55,8 +97,11 @@ share passes. `spec/oracle` compares them with the truth instead:
|
|
|
55
97
|
are compared with the recorded states. Two windows that meet between
|
|
56
98
|
transactions, or inside one, must report each step once, as the window
|
|
57
99
|
spanning both does, through both `activity_timeline` and `analyze_many`.
|
|
100
|
+
The transactions take turns between no author, `alice`, and `bob`, and
|
|
101
|
+
the same windows filtered to alice's versions must report exactly the
|
|
102
|
+
unfiltered steps of the transactions she saved a version in.
|
|
58
103
|
|
|
59
|
-
|
|
104
|
+
Five more generators cover other shapes. `scoped_membership_spec.rb` moves
|
|
60
105
|
notes in and out of scoped associations (conditions, order, limit, and
|
|
61
106
|
offset) and compares the members at every version with Active Record's own
|
|
62
107
|
answer. `tree_history_spec.rb` edits a tree of one model, so a root can sit
|
|
@@ -70,8 +115,13 @@ detaches, creates, renames, and destroys tags between checkpoints. HABTM
|
|
|
70
115
|
membership is known only at root versions, so it expects what the
|
|
71
116
|
[reference](reference.md#habtm-limitation) describes: at each point, the
|
|
72
117
|
members the next root version recorded, as each was then, and only once it
|
|
73
|
-
exists.
|
|
74
|
-
|
|
118
|
+
exists. `shapes_history_spec.rb` edits two boards and the records around them:
|
|
119
|
+
a polymorphic owner, cards that use single-table inheritance and change type,
|
|
120
|
+
comments that move between boards and cards (`as:`), labels with a default
|
|
121
|
+
scope, and scoped and ranked associations to the cards. Its checks, in
|
|
122
|
+
`spec/support/graph_oracle.rb`, follow any model's associations, so a new
|
|
123
|
+
shape needs only models and edits. These four read the expected states with
|
|
124
|
+
plain Active Record, not through the gem.
|
|
75
125
|
|
|
76
126
|
`replay_differential_spec.rb` checks activity against the gem's own full
|
|
77
127
|
snapshots instead. Activity carries each snapshot forward from the previous
|
|
@@ -84,22 +134,143 @@ Mutant cannot check that carrying forward: a mutation that turns it off
|
|
|
84
134
|
falls back to a full snapshot, which gives the same answers, more slowly. This
|
|
85
135
|
check is what catches one that gives a different answer.
|
|
86
136
|
|
|
137
|
+
`unversioned_writes_spec.rb` mixes saves with `update_columns` writes,
|
|
138
|
+
several to a transaction, and logs every write. Each change row must match
|
|
139
|
+
the write that made it: one credited to a version ends at a value that
|
|
140
|
+
version recorded, one credited to no version at a value an `update_columns`
|
|
141
|
+
wrote, and such a write whose value is read again has a row of its own.
|
|
142
|
+
With only the rows of versions kept, each article and comment must end at
|
|
143
|
+
the value of its last recorded save.
|
|
144
|
+
|
|
145
|
+
Every oracle that reads an activity timeline from end to end also checks its
|
|
146
|
+
net changes (`spec/support/net_changes_check.rb`). With every row kept, each
|
|
147
|
+
record's `before` and `after` must be its state where the step of its first
|
|
148
|
+
row starts and where the timeline ends, read from the whole snapshot tree,
|
|
149
|
+
and the record must be listed exactly when the two differ.
|
|
150
|
+
|
|
87
151
|
```console
|
|
88
152
|
mise exec -- bundle exec rake spec_oracle
|
|
89
153
|
ORACLE_SEEDS=1..200 ORACLE_STEPS=40 mise exec -- bundle exec rake spec_oracle
|
|
90
154
|
```
|
|
91
155
|
|
|
92
|
-
The
|
|
156
|
+
The 200-seed run is about 4,000 examples and takes three hours or more in one
|
|
157
|
+
process. Its database is in memory, so you can split it by seed range and run
|
|
158
|
+
the parts side by side, each in its own shell: `ORACLE_SEEDS=1..25`, then
|
|
159
|
+
`26..50`, and so on. Eight such parts took about 25 minutes. Check that each
|
|
160
|
+
part ran all its examples: a run stopped early, by `timeout` for example,
|
|
161
|
+
still ends with "N examples, 0 failures" for the ones it ran. Adding
|
|
162
|
+
`SPEC_OPTS=--dry-run` to the same command prints how many there should be.
|
|
163
|
+
|
|
164
|
+
The default seeds keep the run short; `rake spec` includes it, so
|
|
93
165
|
the database jobs run it too. Mutant does not, because it would slow every
|
|
94
|
-
mutation. A failure prints its seed
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
166
|
+
mutation. A failure prints its seed, the transactions it made, its first five
|
|
167
|
+
mismatches (`ORACLE_SHOW=50` prints more), and the command that reduces it.
|
|
168
|
+
|
|
169
|
+
A scheduled workflow, `.github/workflows/oracle.yml`, runs 200 more seeds each
|
|
170
|
+
night with `ORACLE_STEPS=40`, in eight jobs of 25. The seeds move on 200 a day
|
|
171
|
+
from seed 201, so each night tries histories no run has; run by hand, the
|
|
172
|
+
workflow takes the first of its 200 seeds as `first_seed`. A job reduces the
|
|
173
|
+
first two examples that fail and keeps its log and `tmp/oracle` as an
|
|
174
|
+
artifact: copy that `tmp/oracle` into a checkout and run the `Replay it:`
|
|
175
|
+
command from the log.
|
|
98
176
|
|
|
99
177
|
When a bug turns out to depend on a schema, configuration, or kind of edit,
|
|
100
178
|
add it to the generator or as a new context, so the whole class of bug stays
|
|
101
179
|
covered.
|
|
102
180
|
|
|
181
|
+
### Reducing a failure
|
|
182
|
+
|
|
183
|
+
`ORACLE_SHRINK=1` cuts a failing history down to the few steps that matter, in
|
|
184
|
+
the oracles and the consistency checks alike. A failure ends with the command,
|
|
185
|
+
which runs that example alone with the settings that decide its history:
|
|
186
|
+
|
|
187
|
+
```console
|
|
188
|
+
ORACLE_SEEDS=103 ORACLE_SHRINK=1 mise exec -- bundle exec rspec 'spec/oracle/shapes_history_spec.rb[1:1]'
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The generators draw their random choices through `Oracle.random(seed)`
|
|
192
|
+
(`spec/support/oracle_choices.rb`). It hands out what `Random.new(seed)`
|
|
193
|
+
would, so a seed builds the history it always has, and it keeps each draw,
|
|
194
|
+
grouped by step. When an example fails, the reducer
|
|
195
|
+
(`spec/support/oracle_reducer.rb`) runs it again with runs of steps left out,
|
|
196
|
+
then with each remaining choice set to the first one, such as the first
|
|
197
|
+
operation in a generator's list. An example that builds a history for each
|
|
198
|
+
seed, such as the article oracle's windows that meet inside a transaction,
|
|
199
|
+
first loses whole histories, half of them at a time, since every run builds
|
|
200
|
+
them all. The reducer keeps each change that fails with the same first
|
|
201
|
+
mismatch, numbers aside, and stops when no change helps or after
|
|
202
|
+
`ORACLE_SHRINK_RUNS` runs (300 by default). Leaving a step out keeps the
|
|
203
|
+
other steps' choices as they were, though they may then act on different
|
|
204
|
+
records. `ORACLE_SHRINK_EXAMPLES` caps how many failing examples one run
|
|
205
|
+
reduces; the others just print the command.
|
|
206
|
+
|
|
207
|
+
The example then fails with the reduced history: how many steps were left,
|
|
208
|
+
the versions it wrote if it built one history, its mismatches, and a command
|
|
209
|
+
that replays it from a file in `tmp/oracle`, followed by the original
|
|
210
|
+
failure. Tried against a bug injected into activity's carry-forward, it
|
|
211
|
+
brought one example of each generator from 20 to 66 steps down to 2 to 5, in
|
|
212
|
+
21 to 38 runs, taking from 4 seconds to 5 minutes; the shapes oracle's checks
|
|
213
|
+
are the slowest. Write the reduced history as a named spec beside the code it
|
|
214
|
+
covers, so the cause is readable without the generator.
|
|
215
|
+
|
|
216
|
+
A generator runs each loop of random steps as `@random.steps(count) { ... }`
|
|
217
|
+
rather than `count.times`, so the reducer can tell its steps apart. A new
|
|
218
|
+
generator should too.
|
|
219
|
+
|
|
220
|
+
## Comparison properties
|
|
221
|
+
|
|
222
|
+
The oracles compute the change they expect with `PaperTrailDiff::Engine`, so a
|
|
223
|
+
bug in the engine itself passes them. `spec/unit/engine_properties_spec.rb`
|
|
224
|
+
checks the engine on its own, over a few hundred generated pairs of snapshots
|
|
225
|
+
(`spec/support/snapshot_cases.rb`): attributes, to-one records and
|
|
226
|
+
collections two levels deep, with mixed id types, and collections carried
|
|
227
|
+
forward one record at a time, as activity builds them. For every pair:
|
|
228
|
+
|
|
229
|
+
- an equal snapshot built separately, with its keys and records in another
|
|
230
|
+
order, compares as no change;
|
|
231
|
+
- the diff, applied to the first snapshot, gives the second, so it misses no
|
|
232
|
+
change and reports none wrongly (`spec/support/diff_algebra.rb` applies a
|
|
233
|
+
diff from its hash alone, without the engine);
|
|
234
|
+
- comparing the other way gives the opposite diff;
|
|
235
|
+
- every change reported is a real one, in attribute name and record order;
|
|
236
|
+
- a collection carried forward reports what the same collection built whole
|
|
237
|
+
does;
|
|
238
|
+
- nothing in the diff can be changed.
|
|
239
|
+
|
|
240
|
+
`spec/unit/nested_comparator_properties_spec.rb` does the same for the values
|
|
241
|
+
inside a JSON column, including JSON text, symbol keys, and arrays, which are
|
|
242
|
+
reported by membership.
|
|
243
|
+
|
|
244
|
+
`spec/unit/net_changes_properties_spec.rb` checks the fold behind
|
|
245
|
+
`net_changes`, over generated histories of a few records
|
|
246
|
+
(`spec/support/snapshot_world.rb`) in which a record has one state wherever a
|
|
247
|
+
snapshot reaches it: comments that come and go, replies that move between
|
|
248
|
+
comments, an author who reviews several, and tags. For every history:
|
|
249
|
+
|
|
250
|
+
- the rows of a run of steps fold into each record's change from the run's
|
|
251
|
+
first state to its last, whether the run is passed alone or picked out of
|
|
252
|
+
the whole history by the rows kept;
|
|
253
|
+
- the root comes first, then each record in the order of its first kept
|
|
254
|
+
change, with each source once;
|
|
255
|
+
- kept alone, the rows that move records in and out leave each record as its
|
|
256
|
+
last move left it;
|
|
257
|
+
- a record that stayed changes only in fields a kept row set.
|
|
258
|
+
|
|
259
|
+
They take about a second and run with the unit specs. Each is named after
|
|
260
|
+
what it checks rather than its class, so mutant, which runs only the specs
|
|
261
|
+
that name a mutated class, leaves them out: run with every mutation of
|
|
262
|
+
`Engine`, `NestedComparator`, `NetChange`, and `NetChanges`, they nearly
|
|
263
|
+
doubled its work, from 15 to 27 minutes of worker time, while the classes'
|
|
264
|
+
own specs kill every mutation without them. Name a new property spec the
|
|
265
|
+
same way.
|
|
266
|
+
A failure names its case. The cases start small and grow, so the first one
|
|
267
|
+
that fails is a small one. `PROPERTY_SEED` and `PROPERTY_CASES` choose other
|
|
268
|
+
and more cases:
|
|
269
|
+
|
|
270
|
+
```console
|
|
271
|
+
PROPERTY_SEED=2 PROPERTY_CASES=5000 mise exec -- bundle exec rspec spec/unit/engine_properties_spec.rb
|
|
272
|
+
```
|
|
273
|
+
|
|
103
274
|
## Mutation testing
|
|
104
275
|
|
|
105
276
|
[Mutant](https://github.com/mbj/mutant) changes the library one expression at
|
|
@@ -107,31 +278,48 @@ a time and expects a spec to fail each time. A change that every spec still
|
|
|
107
278
|
passes is behavior nothing checks. `mutant.yml` lists the classes it mutates:
|
|
108
279
|
|
|
109
280
|
- what counts as a change: `Engine`, `CollectionComparator`,
|
|
110
|
-
`CollectionIdentityIndex`, and `
|
|
111
|
-
- which columns are compared: `SnapshotNormalizer
|
|
281
|
+
`CollectionIdentityIndex`, `NestedComparator`, and `CollectionTransition`;
|
|
282
|
+
- which columns are compared, and how precisely times are: `SnapshotNormalizer`,
|
|
283
|
+
`SnapshotPool`, and `StoredTimePrecision`;
|
|
284
|
+
- which endpoints a call accepts, and which item and model each names:
|
|
285
|
+
`Endpoint` and `EndpointKind`;
|
|
112
286
|
- which versions a range reads: `TimeRange`, `TimelineRange`, `VersionRange`,
|
|
113
|
-
`TimeVersionRange`,
|
|
114
|
-
|
|
115
|
-
`
|
|
116
|
-
-
|
|
287
|
+
`TimeVersionRange`, `RootVersionSelection`, `RootVersionPlan`,
|
|
288
|
+
`TransactionCut`, `OpeningTransactions`, `VersionBoundary`, and
|
|
289
|
+
`VersionQuery`;
|
|
290
|
+
- which versions a batch or filter reads: `AnalysisBatch`,
|
|
291
|
+
`BatchedRootVersions`, `BatchedRootAnalyses`, `BatchBoundaryResolver`,
|
|
292
|
+
`DeletedAnalysisBatch`, `HistoricalFilter`, and `VersionScopeFilter`;
|
|
293
|
+
- whether a read sees one database snapshot: `ReadSnapshot`;
|
|
294
|
+
- what a version recorded: `RecordedChanges`, `RecordedChangesReader`, and
|
|
295
|
+
`RecordedClass`;
|
|
117
296
|
- how a step flattens into rows: `ChangeRow` and `ChangeRows`;
|
|
118
|
-
- which records a scope or report selects:
|
|
119
|
-
`
|
|
120
|
-
`DeletedRootFilter`;
|
|
297
|
+
- which records a scope or report selects, and in what order:
|
|
298
|
+
`ScopedRootSelection`, `TotalOrder`, `AssociationActivitySelection`,
|
|
299
|
+
`AssociationActivityEdge`, and `DeletedRootFilter`;
|
|
121
300
|
- which children and targets a record had at each point:
|
|
122
|
-
`PreparedHistoryLoader`, `PreparedEdgeLoader`,
|
|
123
|
-
`ActivityTargetCandidateLoader`, and
|
|
301
|
+
`PreparedHistoryLoader`, `PreparedEdgeLoader`, `ActivityChildCandidateLoader`,
|
|
302
|
+
`PreparedChildCandidates`, `ActivityTargetCandidateLoader`, and
|
|
303
|
+
`PreparedActivityIndex`;
|
|
124
304
|
- where an activity range starts and ends, and which association history its
|
|
125
305
|
query reads: `ActivityRange` and `VersionAssociationCandidateScope`;
|
|
126
|
-
- what activity a record shows: `ActivityTimelineBuilder
|
|
127
|
-
`
|
|
128
|
-
|
|
129
|
-
`
|
|
306
|
+
- what activity a record shows: `ActivityTimelineBuilder`,
|
|
307
|
+
`ActivityVersionCollector`, `ActivityHistoryBuilder`, `ActivityRootSteps`,
|
|
308
|
+
`ActivityTransactionGrouper`, `ActivityTransactionGroups`,
|
|
309
|
+
`ActivityTreeFilter`, `ActivityScopeFilter`, and `ActivityView`;
|
|
310
|
+
- what an update did to a record, and whether it moved the record to another
|
|
311
|
+
owner: `ActivitySnapshotDelta`;
|
|
312
|
+
- where in a carried snapshot an event's record sits: `ActivityEventRouteFinder`;
|
|
313
|
+
- which association paths a request accepts: `AssociationTraversal`,
|
|
314
|
+
`AssociationKey`, and `VersionTable`;
|
|
130
315
|
- whether a transaction's HABTM members are one record's:
|
|
131
316
|
`HabtmTransactionOwners`;
|
|
132
|
-
- which association paths history cannot read exactly
|
|
317
|
+
- which association paths history cannot read exactly, and whether a request
|
|
318
|
+
reads one with PT-AT: `ApproximatePaths` and `FallbackPaths`;
|
|
133
319
|
- which records an association scope admits, and how it ranks them:
|
|
134
|
-
`ScopeCondition` and `ScopeRanking
|
|
320
|
+
`ScopeCondition` and `ScopeRanking`;
|
|
321
|
+
- the helpers these share, which order versions, name records, and copy
|
|
322
|
+
values: `Support`.
|
|
135
323
|
|
|
136
324
|
The specs for the classes that read the database use tables of their own
|
|
137
325
|
(`spec/support/filter_database.rb`, `spec/support/normalizer_database.rb`,
|
|
@@ -150,14 +338,32 @@ behavior can still name the class it checks with metadata, as the activity
|
|
|
150
338
|
window specs do: `RSpec.describe 'Activity over a window', mutant_expression:
|
|
151
339
|
'PaperTrailDiff::ActivityTimelineBuilder'`.
|
|
152
340
|
|
|
341
|
+
Mutant runs an example it picks whatever its `if:` or `unless:` metadata
|
|
342
|
+
says. An example that needs one database calls `skip` on the others instead,
|
|
343
|
+
as `spec/unit/read_snapshot_spec.rb` does for SQL Server.
|
|
344
|
+
|
|
153
345
|
Mutant counts a mutation that runs past its time limit as caught, so
|
|
154
346
|
`mutant.yml` sets the limit well above the time the whole suite takes. With
|
|
155
347
|
mutant's 5-second default, mutations no spec caught were reported as caught.
|
|
156
348
|
|
|
349
|
+
A group nested for one method, such as `describe '.call'`, names that method,
|
|
350
|
+
and mutant then runs only that group for it, so the group must catch every
|
|
351
|
+
mutation in the method by itself. A private method gets every example of its
|
|
352
|
+
class. Mutant cannot reach a method that `module_function` defines: it mutates
|
|
353
|
+
the private copy no caller uses. The mutated modules define their methods with
|
|
354
|
+
`def self.` instead.
|
|
355
|
+
|
|
157
356
|
In CI, a pull request mutates only the methods it changes. The full set runs
|
|
158
357
|
nightly in `.github/workflows/mutation.yml`, and only when `main` has a commit
|
|
159
358
|
that has not passed yet. Start it by hand from the Actions tab with "Run
|
|
160
|
-
workflow".
|
|
359
|
+
workflow". Both split the methods across four jobs with
|
|
360
|
+
`script/mutant_shard.rb`, which takes every fourth method in mutant's listing,
|
|
361
|
+
so that a class holding most of a run's methods is split as well. To run one
|
|
362
|
+
shard locally, as the pull request job does:
|
|
363
|
+
|
|
364
|
+
```console
|
|
365
|
+
BUNDLE_GEMFILE=gemfiles/mutant.gemfile mise exec -- ruby script/mutant_shard.rb 0 4 origin/main
|
|
366
|
+
```
|
|
161
367
|
|
|
162
368
|
Mutant needs Ruby 3.3 or newer, so it has its own bundle:
|
|
163
369
|
|
|
@@ -193,8 +399,10 @@ increasing, in whole microseconds, for the test process. ActiveRecord
|
|
|
193
399
|
timestamps, PaperTrail's `created_at`, and windows built from `Time.now` all
|
|
194
400
|
read it, so they stay consistent however the host clock moves. The benchmark
|
|
195
401
|
workload, `benchmark/support/workload.rb`, loads it too, because a step back
|
|
196
|
-
could date a root's destroy before its last update
|
|
197
|
-
|
|
402
|
+
could date a root's destroy before its last update, and so does the run of
|
|
403
|
+
`examples/demo.rb` in `spec/association/demo_script_spec.rb`, whose versions
|
|
404
|
+
are saved microseconds apart. It affects only the specs, the benchmark, and
|
|
405
|
+
that run; the gem and the demo itself read the ordinary clock.
|
|
198
406
|
|
|
199
407
|
## Other databases locally
|
|
200
408
|
|
|
@@ -23,9 +23,9 @@ module PaperTrailDiff
|
|
|
23
23
|
return [false, nil] unless %w[update destroy].include?(version.event.to_s)
|
|
24
24
|
|
|
25
25
|
routes = @route_finder.belongs_to_routes(
|
|
26
|
-
|
|
26
|
+
RecordedClass.of_endpoint(root_endpoint), tree, version.item_type.to_s
|
|
27
27
|
)
|
|
28
|
-
return [false, nil] if routes.empty? || scoped_route?(routes)
|
|
28
|
+
return [false, nil] if routes.empty? || ActivityEventRouteFinder.scoped_route?(routes)
|
|
29
29
|
|
|
30
30
|
snapshot = previous
|
|
31
31
|
routes.each do |route|
|
|
@@ -43,15 +43,6 @@ module PaperTrailDiff
|
|
|
43
43
|
# @rbs @record_resolver: ActivityEventRecordResolver
|
|
44
44
|
# @rbs @record_normalizer: ActivityEventRecordNormalizer
|
|
45
45
|
|
|
46
|
-
# An edit can move a target into or out of a scope, which a replacement
|
|
47
|
-
# in place cannot show, so a scoped route's branch is read again instead.
|
|
48
|
-
#: (Array[Array[untyped]]) -> bool
|
|
49
|
-
def scoped_route?(routes)
|
|
50
|
-
routes.any? do |route|
|
|
51
|
-
route.any? { |entry| ScopeCondition.scoped_path?(entry.fetch(1)) }
|
|
52
|
-
end
|
|
53
|
-
end
|
|
54
|
-
|
|
55
46
|
#: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
|
|
56
47
|
def normalized_route_record(route, version, normalizer, root_endpoint, context_endpoint)
|
|
57
48
|
record = @record_resolver.record_after(version, direct: route.last.fetch(2).empty?)
|
|
@@ -117,10 +108,5 @@ module PaperTrailDiff
|
|
|
117
108
|
model = AssociationTraversal.named_class(record.type.to_s)
|
|
118
109
|
!model.nil? && model.base_class == Endpoint.model_class(version).base_class
|
|
119
110
|
end
|
|
120
|
-
|
|
121
|
-
#: (untyped) -> untyped
|
|
122
|
-
def endpoint_model_class(endpoint)
|
|
123
|
-
Endpoint.version?(endpoint) ? RecordedClass.for(endpoint) : endpoint.class
|
|
124
|
-
end
|
|
125
111
|
end
|
|
126
112
|
end
|
|
@@ -26,26 +26,16 @@ module PaperTrailDiff
|
|
|
26
26
|
private_constant :NOT_READ, :NOT_READ_MESSAGE
|
|
27
27
|
|
|
28
28
|
class << self
|
|
29
|
-
# `recorded:`
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#: (untyped, ?recorded:
|
|
29
|
+
# `recorded:` reads the version's recorded changes, or is nil when they
|
|
30
|
+
# were not asked for. Reading them decodes `object_changes`, which waits
|
|
31
|
+
# until a caller reads them, and which one who never does should not pay.
|
|
32
|
+
#: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
|
|
33
33
|
def from_version(version, recorded: nil)
|
|
34
|
-
|
|
35
|
-
kind: :version,
|
|
36
|
-
version_id: version.id,
|
|
37
|
-
item_type: version.item_type,
|
|
38
|
-
item_id: version.item_id,
|
|
39
|
-
recorded_at: version.created_at,
|
|
40
|
-
event: version.event,
|
|
41
|
-
whodunnit: version.whodunnit,
|
|
42
|
-
transaction_id: VersionBoundary.transaction_id(version),
|
|
43
|
-
recorded_changes: recorded_changes(version, recorded)
|
|
44
|
-
)
|
|
34
|
+
of_version(version, :version, recorded)
|
|
45
35
|
end
|
|
46
36
|
|
|
47
37
|
# The current record has no version, so it recorded nothing.
|
|
48
|
-
#: (untyped, captured_at: untyped, ?recorded:
|
|
38
|
+
#: (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
|
|
49
39
|
def current(record, captured_at:, recorded: nil)
|
|
50
40
|
new(
|
|
51
41
|
kind: :current,
|
|
@@ -60,10 +50,26 @@ module PaperTrailDiff
|
|
|
60
50
|
# The state a `destroy` version leaves behind. A version records the state
|
|
61
51
|
# before its own event, so the boundary built from a destroy version still
|
|
62
52
|
# holds the record; this one is the absence that follows it.
|
|
63
|
-
#: (untyped, ?recorded:
|
|
53
|
+
#: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
|
|
64
54
|
def destroyed(version, recorded: nil)
|
|
55
|
+
of_version(version, :destroyed, recorded)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# Where a change saved without a version came from, such as an
|
|
59
|
+
# `update_columns` call: no version, event, author or time recorded it,
|
|
60
|
+
# so it has none to report. A change row names it as its source.
|
|
61
|
+
#: (item_type: String, item_id: untyped) -> ActivityBoundary
|
|
62
|
+
def unversioned(item_type:, item_id:)
|
|
63
|
+
new(kind: :unversioned, version_id: nil, item_type: item_type, item_id: item_id,
|
|
64
|
+
recorded_at: nil, recorded_changes: nil)
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
private
|
|
68
|
+
|
|
69
|
+
#: (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
|
|
70
|
+
def of_version(version, kind, recorded)
|
|
65
71
|
new(
|
|
66
|
-
kind:
|
|
72
|
+
kind: kind,
|
|
67
73
|
version_id: version.id,
|
|
68
74
|
item_type: version.item_type,
|
|
69
75
|
item_id: version.item_id,
|
|
@@ -75,18 +81,17 @@ module PaperTrailDiff
|
|
|
75
81
|
)
|
|
76
82
|
end
|
|
77
83
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
def recorded_changes(version, ignore)
|
|
82
|
-
return NOT_READ if ignore.nil?
|
|
84
|
+
#: (untyped, RecordedChangesReader?) -> untyped
|
|
85
|
+
def recorded_changes(version, reader)
|
|
86
|
+
return NOT_READ if reader.nil?
|
|
83
87
|
|
|
84
|
-
|
|
88
|
+
RecordedChangesReader::Pending.new(reader, version)
|
|
85
89
|
end
|
|
86
90
|
end
|
|
87
91
|
|
|
88
92
|
# `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
|
|
89
|
-
# for the version
|
|
93
|
+
# for the version, or a RecordedChangesReader::Pending that reads it when
|
|
94
|
+
# first asked; leave it out when they were not read.
|
|
90
95
|
#: (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
|
|
91
96
|
def initialize( # rubocop:disable Metrics/ParameterLists
|
|
92
97
|
kind:,
|
|
@@ -121,7 +126,8 @@ module PaperTrailDiff
|
|
|
121
126
|
def recorded_changes
|
|
122
127
|
raise ConfigurationError, NOT_READ_MESSAGE unless recorded_changes?
|
|
123
128
|
|
|
124
|
-
@recorded_changes
|
|
129
|
+
changes = @recorded_changes
|
|
130
|
+
changes.is_a?(RecordedChangesReader::Pending) ? changes.value : changes
|
|
125
131
|
end
|
|
126
132
|
|
|
127
133
|
# Whether this boundary's recorded changes were read.
|
|
@@ -145,6 +151,11 @@ module PaperTrailDiff
|
|
|
145
151
|
kind == :destroyed
|
|
146
152
|
end
|
|
147
153
|
|
|
154
|
+
#: () -> bool
|
|
155
|
+
def unversioned?
|
|
156
|
+
kind == :unversioned
|
|
157
|
+
end
|
|
158
|
+
|
|
148
159
|
#: (?metadata: bool) -> Hash[Symbol, untyped]
|
|
149
160
|
def to_h(metadata: false)
|
|
150
161
|
value = {
|
|
@@ -160,7 +171,7 @@ module PaperTrailDiff
|
|
|
160
171
|
record: record.to_h)
|
|
161
172
|
return value unless recorded_changes?
|
|
162
173
|
|
|
163
|
-
value.merge(recorded_changes:
|
|
174
|
+
value.merge(recorded_changes: recorded_changes&.transform_values(&:to_h))
|
|
164
175
|
end
|
|
165
176
|
end
|
|
166
177
|
|
|
@@ -181,30 +192,38 @@ module PaperTrailDiff
|
|
|
181
192
|
# which holds every event in it: an attribution that names only the first
|
|
182
193
|
# would credit the rest of the save to whoever opened it.
|
|
183
194
|
attr_reader :sources #: Array[ActivityBoundary]
|
|
195
|
+
# @api private
|
|
196
|
+
# What credits this step's change rows, which a transaction group extends
|
|
197
|
+
# over the steps it merges.
|
|
198
|
+
attr_reader :attribution #: ChangeAttribution?
|
|
184
199
|
|
|
185
200
|
# Compares two reconstructed states and keeps them only when asked, which is
|
|
186
201
|
# every caller's shape: the diff always comes from the pair, the pair itself
|
|
187
202
|
# is retained on request.
|
|
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
|
|
203
|
+
#: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
|
|
204
|
+
def self.between(from_boundary:, to_boundary:, from_snapshot:, to_snapshot:, retain:, sources: nil, attribution: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
|
|
190
205
|
new(
|
|
191
206
|
from_boundary: from_boundary,
|
|
192
207
|
to_boundary: to_boundary,
|
|
193
208
|
diff: Engine.compare(from_snapshot, to_snapshot),
|
|
194
209
|
from_snapshot: (from_snapshot if retain),
|
|
195
210
|
to_snapshot: (to_snapshot if retain),
|
|
196
|
-
sources: sources
|
|
211
|
+
sources: sources,
|
|
212
|
+
attribution: attribution
|
|
197
213
|
)
|
|
198
214
|
end
|
|
199
215
|
|
|
200
|
-
|
|
201
|
-
|
|
216
|
+
# `attribution` credits each change row to the version that made it (see
|
|
217
|
+
# ChangeAttribution); without it, every row names `source_boundary`.
|
|
218
|
+
#: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
|
|
219
|
+
def initialize(from_boundary:, to_boundary:, diff:, from_snapshot: nil, to_snapshot: nil, sources: nil, attribution: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
|
|
202
220
|
@from_boundary = from_boundary
|
|
203
221
|
@to_boundary = to_boundary
|
|
204
222
|
@diff = diff
|
|
205
223
|
@from_snapshot = from_snapshot
|
|
206
224
|
@to_snapshot = to_snapshot
|
|
207
225
|
@sources = (sources || [from_boundary]).dup.freeze
|
|
226
|
+
@attribution = attribution
|
|
208
227
|
freeze
|
|
209
228
|
end
|
|
210
229
|
|
|
@@ -218,10 +237,12 @@ module PaperTrailDiff
|
|
|
218
237
|
#: () -> ActivityBoundary
|
|
219
238
|
def source_boundary = from_boundary
|
|
220
239
|
|
|
221
|
-
# The diff as flat rows, each
|
|
240
|
+
# The diff as flat rows, each credited to the event that made its change:
|
|
241
|
+
# the version of the row's record that recorded it, an unversioned source
|
|
242
|
+
# for a part saved without a version, or else `source_boundary`.
|
|
222
243
|
#: () -> Array[ChangeRow]
|
|
223
244
|
def change_rows
|
|
224
|
-
ChangeRows.call(diff, source: source_boundary)
|
|
245
|
+
ChangeRows.call(diff, source: source_boundary, attribution: @attribution)
|
|
225
246
|
end
|
|
226
247
|
|
|
227
248
|
# `metadata: true` also lists `sources`, since who made a change is
|