mu-action 0.3.0 → 0.4.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 261d73076a857c43d7c68e5c3585cb3e96d693d54ed104b33abd6a6e897272fd
4
- data.tar.gz: 9a0ac5c6592b3a2715918da63f88d8fec4b45dc6111547e1a545d6a26553e47e
3
+ metadata.gz: 981390b1d576ff6abd5018a1d2e110fbdea7ad13fcf4c3d6bb37050510cdd2a5
4
+ data.tar.gz: 206acaac3c6e02f3af8677adfc9363c26042f07a208f2ce2d07ff5398e516776
5
5
  SHA512:
6
- metadata.gz: ef960929df4e5a7daa07544be3af52a5a952185959fbcc3a21329145e7e465c3f798ff46c0c382f4c63310fbfd3aa611e3e742f506fcbec949b80ebd1463adc4
7
- data.tar.gz: 75a8de3adbc5dbaf4302f233c9314bedf009c5aebd4b12b32422a790a989e75073aaffc8303bc124e2c058b36ae88cd63b1bf37b7ed6edc84cda42fc5ab02b55
6
+ metadata.gz: 789112014861aa15bf4e2ff88b92aeceec577b458766fe5fc4b3e4a99da80e3769a783e79e5b8894caa9e9e23be272b4ad5e77b54cc4588d9032312789f59bfd
7
+ data.tar.gz: 51c1e5d164ef6a5f5296cc3e4f22371295cb0860ac5e3f427af7303714c93942659b07fadeb26099edc311b6a916f3b09817e56bcda0ed69f834714b6629ccdc
data/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [0.4.0] - 2026-11-16
4
+
5
+ ### Breaking
6
+ - `call` must return the `Success(...)` it built, or call `Failure(...)`; so must an around hook, which can also return the result of the chain. Anything else raises a `TypeError`. A raw value used to be returned as the result, without the `result` type being checked, and the last expression of an around hook replaced the result. To use another action's value, write `Success(Other.call!(...))`.
7
+ - A `Failure` of another action returned from `call` becomes the failure of the action, as with `call!`: around hooks see an exception, `after` hooks are skipped and the declared failures are checked. It used to be returned as it was.
8
+ - The context is inherited by an action called directly by a running action, and no longer by a thread or a fiber started by it: pass `context:` explicitly to an action that runs in another thread or fiber. In 0.3.0 a long-lived thread first started inside an action, such as a thread pool worker, kept that action's context for all the work it did later.
9
+ - Declaring a prop named `meta` or `context` raises an `ArgumentError`. In 0.3.0 such a prop was silently replaced the first time the action was instantiated.
10
+ - `record_props` raises an `ArgumentError` when its first argument is not `true` or `false`, and an action raises one when it is called if `record_props` names something that is not one of its props. `record_props :email` used to record every prop, and a misspelled name in `except:` left the prop recorded.
11
+ - An around block that takes one parameter receives the chain, as an around method does. It used to receive the action. An around block that takes no parameter raises an `ArgumentError`, since it could not call the chain.
12
+ - `failure :code, from: OtherAction` declares a detail named `from`; it no longer also takes the failures of `OtherAction`. Write `failure from: OtherAction` on its own.
13
+ - Results are immutable. `Success` and `Failure` are frozen and have no writer: `result.value = …`, `result.meta = …`, `result.error = …`, `result.details = …` and `result[:value] = …` no longer exist, nor does the hash-style reader `result[:value]`. The contents of `meta` and `details` can still change.
14
+
15
+ ### Changed
16
+ - The message of the `FailureError` raised by `call!` or `run!` names the action and the keys of the details, as in `CreateUser failed: invalid (details: errors)`. It was the error alone. The values of the details are not shown.
17
+ - An action class gets twelve class methods and no other: `call`, `call!`, `result`, `before`, `after`, `around`, `before_hooks`, `after_hooks`, `around_hooks`, `failure`, `failures` and `record_props`. The README documents them. The undocumented `own_failures`, `failure_sources`, `failure_lineage`, `declares_failures?` and `props_recording` are gone, and a class method of an action with one of those names, or named `register_hook`, no longer replaces part of the library.
18
+ - `before`, `after`, `around`, `failure` and `record_props` return `nil`. They returned internal lists.
19
+ - `before_hooks`, `after_hooks` and `around_hooks` return a new list each time, for inspection: changing it does not change the hooks that run.
20
+ - Hooks, failure checks and metadata recording no longer add methods to an action. An action gets seven methods from `Mu::Action` (`meta`, `context`, `Success`, `Failure`, `run`, `run!` and the private `initialize_meta`); the README documents them, and each can be overridden with `super`. A method of an action named `with_hooks`, `check_failure` or `resolve_method`, for example, no longer replaces part of the library.
21
+ - A subclass follows its parent class. A hook, a declared failure or a `record_props` choice added to a class after one of its subclasses was defined now applies to that subclass; each used to be copied when the subclass was defined. A parent's hooks always run before those of its subclasses.
22
+ - Literal 1.9 or later is required; 1.7 and 1.8 are no longer supported. CI only tested 1.9, and on 1.7 a prop default could not read `context`.
23
+ - The `meta` and `context` props are declared when `Mu::Action` is included, before the action's own props. They were added the first time the class was instantiated.
24
+ - The library is split into one file per feature under `lib/mu/action/`. The internal modules `Initializer`, `MetaPropAdder`, `HookPropagator` and `FailureChecking` are replaced by `Context`, `Metadata`, `Hooks` and `Failures`. Like every constant of `Mu::Action`, these names come before top-level constants inside action classes; the README lists them.
25
+ - The README documents the order in which hooks run, and that after hooks only run when the action succeeds.
26
+ - The README warns that a broad `rescue` in `call` catches the error `Failure` raises, and shows how to let it through.
27
+ - The README's section on result types is rewritten as "Typed Results": a domain object as the result, the error a wrong type raises, and results that may be `nil`.
28
+ - The specs run in random order, and `bin/ci` and CI ignore focused examples.
29
+ - `bin/test_readme_examples` reports a failing example with its line in the README and the code of its block, and `bin/console` loads the classes of the README examples.
30
+ - `bin/check` is renamed `bin/ci`. It runs the checks on every supported Ruby version, using asdf, and `bin/ci --current` runs them on the current Ruby only.
31
+ - Development dependencies updated, including json 3, prism 2, erb 6 and rdoc 8. Steep and RBS stay at 2.0 and 4.1, the last versions that support Ruby 3.2.
32
+ - Development now follows agent skills in `.agents/skills` (commits, pull requests, changelog, dependencies, releases, reviews), and `AGENTS.md` is the single guide; `CLAUDE.md` points to it.
33
+
34
+ ### Removed
35
+ - The RBS signatures are no longer shipped in the gem. An application could not load them: they refer to Literal declarations that exist nowhere, and they did not describe the class methods of an action. They stay in the repository for the library's own type check.
36
+ - Guard, its RSpec and RuboCop plugins, and the local Steep plugin (`lib/guard/steep.rb`) from the development tooling.
37
+
38
+ ### Fixed
39
+ - `run!` on an action called from another one is treated as `call!` is: the failure is checked against the failures the outer action declares and kept in `meta[:cause]`. It used to become the outer action's failure unchecked. `run!` now goes through `run`, and raises a `FailureError` that carries the `Failure`.
40
+ - A failure detail can be named `from`, as in `failure :invalid_transition, from: Symbol, to: Symbol`. It was taken as a `from:` action, and the first such failure raised `NoMethodError`.
41
+ - `failure from:` raises an `ArgumentError` for anything that is not an action class, and actions that name each other in `from:` no longer overflow the stack.
42
+ - A top-level `Configuration` constant is no longer hidden inside action classes: the `Mu::Action::Configuration` module is gone.
43
+ - A prop default can read `context`. It used to get `nil` or the context depending on the order in which the classes were defined and called.
44
+ - The metadata of an action is initialized once. It was initialized twice for a class that includes `Mu::Action` directly.
45
+ - `record_props` accepts prop names given as strings. They were ignored, so `record_props except: %w[password]` recorded the password.
46
+ - A subclass with no props of its own runs its parent's `initialize`.
47
+ - A `meta:` hash passed by a caller is no longer modified by an `after_initialize` method.
48
+ - `around { |chain| chain.call }` no longer skips the around hooks declared after it. The block received the action, so `chain.call` ran the action directly.
49
+ - Around hooks accept lambdas that take one parameter, and methods with keyword parameters.
50
+
3
51
  ## [0.3.0] - 2026-11-14
4
52
 
5
53
  ### Breaking
data/README.md CHANGED
@@ -66,6 +66,31 @@ A `Success` result contains the `value` returned by the interactor, while a `Fai
66
66
 
67
67
  A failure will return immediately.
68
68
 
69
+ A result is immutable: it is frozen and has no writer, so a `Success` cannot be turned into another one after the fact. The `meta` and `details` hashes it holds are not frozen.
70
+
71
+ `call` must return the `Success(...)` it built, or call `Failure(...)`. Anything else raises a `TypeError`, so a branch that forgets its `Success` cannot pass for a result:
72
+
73
+ ```ruby
74
+ class Forgetful
75
+ include Mu::Action
76
+
77
+ def call = 42
78
+ end
79
+
80
+ error =
81
+ begin
82
+ Forgetful.call
83
+ rescue TypeError => e
84
+ e
85
+ end
86
+
87
+ assert error.message.include?("call returned 42. It must return Success(...), or call Failure(...)")
88
+ ```
89
+
90
+ To use the value of another interactor, wrap it: `Success(Other.call!(...))`. Returning the `Failure` of another interactor works like `call!`: it becomes the failure of this one.
91
+
92
+ Inside an action class, the constants of `Mu::Action` come before top-level constants with the same name: `Result`, `Success`, `Failure`, `FailureError`, `Context`, `Metadata`, `Hooks`, `Failures`, `ClassMethods`, `VERSION` and `CONTEXT_KEY`. If your application has its own `Result` or `Context` class, for example, write `::Result` or `::Context` inside an action.
93
+
69
94
  ### Calling Interactors
70
95
 
71
96
  Interactors can be called in two ways:
@@ -81,12 +106,27 @@ in Mu::Action::Failure(error:)
81
106
  puts "Failed: #{error}"
82
107
  end
83
108
 
84
- # Returns the value on success, raises an exception on failure
109
+ # Returns the value on success, raises a Mu::Action::FailureError on failure
85
110
  user = CreateUser.call!(email: "jane@example.com", name: "Jane")
86
111
  assert user.name == "Jane"
87
112
  assert user.email == "jane@example.com"
88
113
  ```
89
114
 
115
+ The error raised by `call!` has the `error` and the `details` of the failure, and the `Failure` itself as `failure`. Its message names the interactor, the error and the keys of the details. The values of the details are left out, as they may not belong in a log.
116
+
117
+ ```ruby
118
+ error =
119
+ begin
120
+ CreateUser.call!(email: "existing@example.com", name: "Jane")
121
+ rescue Mu::Action::FailureError => e
122
+ e
123
+ end
124
+
125
+ assert error.error == :user_exists
126
+ assert error.failure.meta[:class] == CreateUser
127
+ assert error.message == "CreateUser failed: user_exists"
128
+ ```
129
+
90
130
  ### Hooks
91
131
 
92
132
  Add cross-cutting concerns with before, after, and around hooks:
@@ -157,47 +197,114 @@ class ProcessPayment
157
197
  end
158
198
  ```
159
199
 
160
- Around hook methods may also receive no arguments and use `yield`, or accept two arguments `(action, chain)` to mirror the block-based signature.
200
+ An around hook takes the chain, or the action and the chain, whether it is a block or a method: `around { |chain| ... }` works like `def wrap_in_transaction(chain)`, and a method can take `(action, chain)` like the block above. A method can also take no argument and use `yield`.
161
201
 
162
- ### Custom Result Types
202
+ An around hook returns the result of the chain. It can also return its own `Success(...)`, to replace the result or to skip the call; anything else raises a `TypeError`.
163
203
 
164
- Define typed results for better API contracts:
204
+ Hooks run in this order: the before hooks, then the around hooks wrapped around `call`, then the after hooks. Hooks of one kind run in the order they were declared, and the first around hook declared is the outermost.
165
205
 
166
206
  ```ruby
167
- class RollaDice
207
+ class Traced
168
208
  include Mu::Action
169
209
 
170
- result _Integer(1..6)
210
+ STEPS = []
211
+
212
+ before { STEPS << :before }
213
+ around { |chain| STEPS << :around_start; chain.call.tap { STEPS << :around_end } }
214
+ after { STEPS << :after }
215
+
216
+ def call = Success(STEPS << :call)
217
+ end
218
+
219
+ Traced.call
220
+ assert Traced::STEPS == %i[before around_start call around_end after]
221
+ ```
222
+
223
+ The before and after hooks run outside the around hooks: a transaction opened by an around hook covers `call`, not what the before and after hooks do.
224
+
225
+ When the interactor fails or raises, in a before hook, in `call` or in an around hook, everything that would follow is skipped. In particular, the after hooks only run when the interactor succeeds.
226
+
227
+ ### Typed Results
228
+
229
+ `result` declares the type of the value an interactor returns. `Success` then only accepts a value of that type:
230
+
231
+ ```ruby
232
+ Quote = Data.define(:amount, :currency)
233
+
234
+ class PriceQuote
235
+ include Mu::Action
236
+
237
+ result Quote
238
+
239
+ prop :quantity, Integer
171
240
 
172
241
  def call
173
- Success rand 1..6
242
+ Failure(:out_of_stock) if @quantity > 100
243
+ Success(Quote.new(amount: @quantity * 250, currency: "CAD"))
174
244
  end
175
245
  end
176
246
 
177
- result = RollaDice.call!
178
- assert (1..6).cover? result
247
+ quote = PriceQuote.call!(quantity: 4)
248
+ assert quote.amount == 1000
179
249
  ```
180
250
 
181
- The result method above is just a shortcut for the type of the value property of the Success class.
251
+ A value of another type is a bug in the interactor, not a failure. `Success` raises a `Literal::TypeError`, which `call` does not turn into a `Failure`:
182
252
 
183
253
  ```ruby
184
- class RollaDice
254
+ class Careless
185
255
  include Mu::Action
186
256
 
187
- class Success < Mu::Action::Success
188
- prop :value, _Integer(1..6), :positional
189
- end
257
+ result Quote
190
258
 
191
- def call
192
- Success rand 1..6
259
+ def call = Success(1000)
260
+ end
261
+
262
+ error =
263
+ begin
264
+ Careless.call
265
+ rescue Literal::TypeError => e
266
+ e
193
267
  end
268
+
269
+ assert error.message.include?("Expected: Quote")
270
+ ```
271
+
272
+ The type can be any [Literal type](https://literal.fun/docs/built-in-types.html), such as a range of integers, or a value that may be `nil`:
273
+
274
+ ```ruby
275
+ class RollDice
276
+ include Mu::Action
277
+
278
+ result _Integer(1..6)
279
+
280
+ def call = Success(rand(1..6))
194
281
  end
195
282
 
196
- result = RollaDice.call!
197
- assert (1..6).cover? result
283
+ class FindNickname
284
+ include Mu::Action
285
+
286
+ result _Nilable(String)
287
+
288
+ prop :name, String
289
+
290
+ def call = Success({ "Robert" => "Bob" }[@name])
291
+ end
292
+
293
+ assert (1..6).cover?(RollDice.call!)
294
+ assert FindNickname.call!(name: "Robert") == "Bob"
295
+ assert FindNickname.call!(name: "Jane").nil?
198
296
  ```
199
297
 
200
- You can refer to the [Literal documentation](https://literal.fun/docs) for more details on the [built-in types](https://literal.fun/docs/built-in-types.html) or see some [example types](https://literal.fun/docs/example-types.html).
298
+ Without `result`, an interactor accepts any value, `nil` included.
299
+
300
+ `result` also gives the interactor its own `Success` class, so a `case` can match the success of one interactor in particular:
301
+
302
+ ```ruby
303
+ case PriceQuote.call(quantity: 4)
304
+ in PriceQuote::Success(value: Quote(amount:))
305
+ assert amount == 1000
306
+ end
307
+ ```
201
308
 
202
309
  ### Failures
203
310
 
@@ -221,6 +328,29 @@ in Mu::Action::Failure(error: :invalid, details: { errors: })
221
328
  end
222
329
  ```
223
330
 
331
+ `Failure` stops the interactor by raising a `Mu::Action::FailureError`, which is a `StandardError`. A `rescue StandardError`, or a bare `rescue`, around it therefore catches the failure along with real errors. When `call` rescues broadly, let the failures through first:
332
+
333
+ ```ruby
334
+ class Charge
335
+ include Mu::Action
336
+
337
+ prop :amount, Integer
338
+
339
+ def call
340
+ Failure(:invalid_amount) unless @amount.positive?
341
+ Success(@amount)
342
+ rescue Mu::Action::FailureError
343
+ raise
344
+ rescue StandardError => e
345
+ Failure(:charge_failed, message: e.message)
346
+ end
347
+ end
348
+
349
+ assert Charge.call(amount: 0).error == :invalid_amount
350
+ ```
351
+
352
+ Without the first `rescue`, this interactor would fail with `:charge_failed` in both cases.
353
+
224
354
  An interactor can declare the failures it returns, with the types of their details. Once it declares any, an undeclared failure or a detail of the wrong type raises an `ArgumentError`. Interactors without declarations accept any failure.
225
355
 
226
356
  ```ruby
@@ -274,6 +404,8 @@ assert result.meta[:cause].meta[:class] == PublishArticle
274
404
 
275
405
  Because the inner failure is raised as an exception, around hooks such as transactions see it and can roll back.
276
406
 
407
+ `failure from:` takes one interactor class or several, and goes on its own line. With an error code, every keyword is a detail, including one named `from`: `failure :invalid_transition, from: Symbol, to: Symbol`.
408
+
277
409
  ### Metadata Tracking
278
410
 
279
411
  Every interactor automatically tracks metadata including class information and property values:
@@ -304,6 +436,105 @@ end
304
436
  assert SignIn.call(email: "jane@example.com", password: "secret").meta[:props] == { email: "jane@example.com" }
305
437
  ```
306
438
 
439
+ A subclass inherits the choice. Every name must be a prop of the interactor: one that is not raises an `ArgumentError` when the interactor is called, so a misspelled name cannot leave a secret recorded.
440
+
441
+ ### The Methods of an Interactor
442
+
443
+ Including `Mu::Action` gives an interactor these methods and no other. Hooks, failure checks and metadata recording run from outside it, so every other method name is yours.
444
+
445
+ - `call`: yours to implement. It returns `Success(...)` or calls `Failure(...)`.
446
+ - `Success(value = nil)`: builds the result of the interactor.
447
+ - `Failure(error, **details)`: checks the failure against the declared ones, then raises, so that nothing after it runs.
448
+ - `meta`: the metadata hash, which the result carries.
449
+ - `context`: what the caller passed as `context:`, or the context of the calling interactor.
450
+ - `run`: runs the interactor and returns its result, a `Success` or a `Failure`. It sets the context and runs the hooks around `call`. `MyAction.call(...)` is `MyAction.new(...).run`.
451
+ - `run!`: calls `run` and returns its `Success`, or raises a `Mu::Action::FailureError` that carries the `Failure`. `MyAction.call!(...)` is `MyAction.new(...).run!.value`.
452
+ - `initialize_meta` (private): fills in `meta` when the interactor is built.
453
+
454
+ Each of them can be overridden, with `super` for the original behavior:
455
+
456
+ ```ruby
457
+ class Import
458
+ include Mu::Action
459
+
460
+ prop :rows, Integer
461
+
462
+ # A default context, when the caller gives none.
463
+ def context = super || { actor: "system" }
464
+
465
+ # A detail added to every failure.
466
+ def Failure(error, **details) = super(error, **details, rows: @rows)
467
+
468
+ def call
469
+ Failure(:empty) if @rows.zero?
470
+ Success(@rows)
471
+ end
472
+
473
+ private
474
+
475
+ # Something else than the props in the metadata.
476
+ def initialize_meta
477
+ super
478
+ meta[:props] = { rows: "#{@rows} rows" }
479
+ end
480
+ end
481
+
482
+ result = Import.call(rows: 0)
483
+
484
+ assert result.details == { rows: 0 }
485
+ assert result.meta[:context] == { actor: "system" }
486
+ assert result.meta[:props] == { rows: "0 rows" }
487
+ ```
488
+
489
+ Two rules apply to an override. `meta` must return the same hash on every call, because hooks write to it and the result shares it. `Success` must return what `super` built, because `call` has to return the result of its own interactor.
490
+
491
+ The class of an interactor gets these methods, and no other:
492
+
493
+ - `call(...)` and `call!(...)`: build the interactor and run it.
494
+ - `result(type)`: the type of the value of its `Success`.
495
+ - `before`, `after`, `around`: register hooks.
496
+ - `before_hooks`, `after_hooks`, `around_hooks`: list the hooks of the class, those of its parent class first. Each hook is a block or the name of a method. These lists are for inspection: changing what they return does not change the hooks that run.
497
+ - `failure`: declares failures.
498
+ - `failures`: the declared failures, with the types of their details.
499
+ - `record_props`: chooses the props recorded in the metadata.
500
+
501
+ ```ruby
502
+ class Audited
503
+ include Mu::Action
504
+
505
+ before :check_access
506
+ after { meta[:audited] = true }
507
+
508
+ def call = Success(:done)
509
+
510
+ private
511
+
512
+ def check_access = nil
513
+ end
514
+
515
+ assert Audited.before_hooks == [:check_access]
516
+ assert Audited.after_hooks.size == 1
517
+ assert Audited.around_hooks.empty?
518
+ ```
519
+
520
+ ### Subclasses
521
+
522
+ A subclass has the hooks of its parent class, followed by its own. It also has its parent's declared failures, and its `record_props` choice unless it makes its own. These follow the parent: a hook added to a parent class applies to its subclasses whenever it is added.
523
+
524
+ ```ruby
525
+ class ApplicationAction
526
+ include Mu::Action
527
+ end
528
+
529
+ class Publish < ApplicationAction
530
+ def call = Success(meta[:checked])
531
+ end
532
+
533
+ ApplicationAction.before { meta[:checked] = true }
534
+
535
+ assert Publish.call! == true
536
+ ```
537
+
307
538
  ### Context
308
539
 
309
540
  Information about who is calling and from where, such as the actor, the account or the channel, goes in `context` rather than in props. It's available in hooks and in `call`, and it's recorded in `meta[:context]`. It can be any object.
@@ -327,10 +558,49 @@ assert result.meta[:archived_by] == "jane"
327
558
 
328
559
  Interactors called by another one inherit its context, so a hook in a nested interactor sees the same actor. Pass `context:` explicitly to override it.
329
560
 
561
+ The context follows the call stack: an interactor inherits it when it is called directly by an interactor that is running. A thread or a fiber started by an interactor does not inherit it, so hand it over explicitly:
562
+
563
+ ```ruby
564
+ class WhoIsActing
565
+ include Mu::Action
566
+
567
+ def call = Success(context && context[:actor])
568
+ end
569
+
570
+ class ActInBackground
571
+ include Mu::Action
572
+
573
+ def call
574
+ inherited = Thread.new { WhoIsActing.call! }.value
575
+ handed_over = Thread.new { WhoIsActing.call!(context:) }.value
576
+ Success([inherited, handed_over])
577
+ end
578
+ end
579
+
580
+ assert ActInBackground.call!(context: { actor: "jane" }) == [nil, "jane"]
581
+ ```
582
+
583
+ `context` and `meta` are reserved prop names: declaring a prop with one of them raises an `ArgumentError`. The context is set before the other props, so a prop default can read it:
584
+
585
+ ```ruby
586
+ class Greet
587
+ include Mu::Action
588
+
589
+ prop :locale, Symbol, default: -> { context ? context[:locale] : :en }
590
+
591
+ def call = Success(@locale == :fr ? "Bonjour" : "Hello")
592
+ end
593
+
594
+ assert Greet.call!(context: { locale: :fr }) == "Bonjour"
595
+ assert Greet.call! == "Hello"
596
+ ```
597
+
330
598
  ## Differences from the Interactor Gem
331
599
 
332
600
  The main difference and the motivation for creating `Mu::Action` is to separate the context into inputs, an output, and metadata. This allows for a more structured approach to handling business logic, making it easier to reason about the flow of data and the state of the application.
333
601
 
602
+ Hooks are also ordered differently: in Interactor, the around hooks wrap the before and after hooks, while here the before and after hooks run outside the around hooks.
603
+
334
604
  ## Development
335
605
 
336
606
  After checking out the repo, run `bin/setup` to install dependencies. Then, run the tests with:
@@ -339,21 +609,27 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
339
609
  bundle exec rspec
340
610
  ```
341
611
 
342
- You can also run `bin/console` for an interactive prompt to experiment with the gem.
612
+ You can also run `bin/console` for an interactive prompt to experiment with the gem. The classes of the examples in this README are loaded in it.
343
613
 
344
614
  To install this gem onto your local machine, run `bundle exec rake install`.
345
615
 
346
- ### Running Tests and Linting
616
+ ### Running the Checks
617
+
618
+ `bin/ci` runs RuboCop, RSpec, Steep and the README examples. It runs them on every supported Ruby version, switching between them with [asdf](https://asdf-vm.com), and installs missing gems from the lockfile.
347
619
 
348
620
  ```bash
349
- # Run all tests
350
- bundle exec rspec
621
+ # Run every check on each supported Ruby version
622
+ bin/ci
351
623
 
352
- # Run linting
353
- bundle exec rubocop
624
+ # Run every check on some Ruby versions only
625
+ bin/ci 3.2 4.0
626
+
627
+ # Run every check on the current Ruby only (no asdf needed)
628
+ bin/ci --current
354
629
 
355
- # Run both tests and linting
356
- bundle exec rake
630
+ # Run the tests or the linter alone
631
+ bundle exec rspec
632
+ bundle exec rubocop
357
633
  ```
358
634
 
359
635
  ## Contributing
@@ -365,11 +641,10 @@ When contributing:
365
641
  1. Fork the repository
366
642
  2. Create your feature branch (`git checkout -b my-new-feature`)
367
643
  3. Write tests for your changes
368
- 4. Ensure all tests pass (`bundle exec rspec`)
369
- 5. Ensure code follows style guidelines (`bundle exec rubocop`)
370
- 6. Commit your changes (`git commit -am 'Add some feature'`)
371
- 7. Push to the branch (`git push origin my-new-feature`)
372
- 8. Create a new Pull Request
644
+ 4. Ensure all checks pass (`bin/ci`)
645
+ 5. Commit your changes (`git commit -am 'Add some feature'`)
646
+ 6. Push to the branch (`git push origin my-new-feature`)
647
+ 7. Create a new Pull Request
373
648
 
374
649
  This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/budu/mu-action/blob/main/CODE_OF_CONDUCT.md).
375
650
 
@@ -0,0 +1,36 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mu
4
+ module Action
5
+ # Fiber-local key holding the context of the running action.
6
+ CONTEXT_KEY = :mu_action_context
7
+
8
+ # The context of an action: what its caller says about who is calling and
9
+ # from where. An action called by another one inherits its context.
10
+ #
11
+ # The context of the running action is kept in a fiber-local variable, so
12
+ # it follows the call stack and nothing else: a thread or a fiber started
13
+ # by an action does not see it. Storage that new threads inherit would
14
+ # give a thread pool worker the context of whichever action happened to
15
+ # start it, for all the work it does later.
16
+ #
17
+ # @api private Applications use what this module adds to action classes,
18
+ # never the module itself.
19
+ module Context
20
+ def self.install(base)
21
+ # The context defaults to the one of the action that is running, if any.
22
+ base.prop :context, base._Nilable(base._Any), default: -> { Thread.current[CONTEXT_KEY] }
23
+ end
24
+
25
+ # Runs the block with the context of the action as the one that the
26
+ # actions it calls inherit.
27
+ def self.with(action)
28
+ previous = Thread.current[CONTEXT_KEY]
29
+ Thread.current[CONTEXT_KEY] = action.context
30
+ yield
31
+ ensure
32
+ Thread.current[CONTEXT_KEY] = previous
33
+ end
34
+ end
35
+ end
36
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Mu
4
+ module Action
5
+ # Exception class for action failures. Carries the error code and its
6
+ # details. When raised by +call!+ or +run!+, it also carries the Failure
7
+ # result, and its message names the action.
8
+ class FailureError < StandardError
9
+ attr_reader :error, :details, :failure
10
+
11
+ def initialize(error, details: {}, failure: nil)
12
+ @error = error
13
+ @details = details
14
+ @failure = failure
15
+ super(summary)
16
+ end
17
+
18
+ private
19
+
20
+ # "CreateUser failed: invalid (details: errors)". The details are named
21
+ # and not shown: their values may not belong in a log.
22
+ def summary
23
+ text = error.to_s
24
+ action = failure&.meta&.[](:class)
25
+ text = "#{action.name} failed: #{text}" if action.is_a?(Module) && action.name
26
+ details.empty? ? text : "#{text} (details: #{details.keys.join(", ")})"
27
+ end
28
+ end
29
+ end
30
+ end