hubbado-sequence 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc373389ca48751e5d60ebc84c00dfd8740b437ec89a53b8d9a1b986ea5c2a48
-  data.tar.gz: 7053947aa597354f5b973832083ebc8cc9e60e4de3a1cee23524045f803a63cd
+  metadata.gz: bae3a73329cdbf0194b5074fae10bd5e2d4035e773ee70f238ca802a5d0f2ae7
+  data.tar.gz: 8ff2d5bc1088333c8480695d411000f7b361efb22e296057c0111f88c0886113
 SHA512:
-  metadata.gz: 240dbbf380bea6a9007872456c97d052a6cedf0f5b716fbffe63876362f7c66f89f18accbf51d1cd99f2ee0f3f377376c7161770e46d85f6314548bc07d6549b
-  data.tar.gz: ef08b3226afc5465ecac7030ca8e36ad9c3a2ecb967530144bb96aad79a670e2085eda9e74d80b4cc05e4617deab78ac0903150ff5ed6b78f4cf1b58a912d778
+  metadata.gz: 16069e3f557800e6c0c18e2f6b52c5bec482d2d8610d244e2679403879bf81ab742bbcf4da74d63a03fbaa12614103e51ffe53a6889d45b6cc3a73509ca3ecd5
+  data.tar.gz: c92c360d5fe1995cf05eefb330ab1949d0870d6ede7fcc308f350e7c23f98118544cda4d218580ba62d12793e7bbf6329af7f2b33a4c0adc6b5d87db2bc85dea

data/CHANGELOG.md

@@ -4,6 +4,117 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.8.0] - Instance calls take only a Ctx; chained pipeline carries the i18n scope
+
+### Changed (breaking)
+
+- **`pipeline` rejects anything but a `Ctx`.** A sequencer's instance
+  `call` takes a `Ctx`, as `docs/design.md` already stated, and
+  `pipeline` now raises `ArgumentError` when it gets keyword arguments or
+  a plain Hash. A spec that calls an instance
+  (`seq = Seq.new; seq.(params: ...)`) must pass
+  `Hubbado::Sequence::Ctx.build(params: ...)`. On a plain Hash, a read of a
+  missing ctx key returned `nil` in the spec while it raised `KeyError` in
+  production through the class-level `.()`, so specs could not find that
+  fault. The class-level `.()` still accepts keyword arguments.
+
+### Fixed
+
+- **A chained `pipeline(ctx).step(...).result` carries the sequencer's
+  i18n scope.** Only the block form tagged its Result, so a sequencer
+  using the chained form got no scope on an instance call, and its
+  parent's scope when nested through `p.invoke`. The pipeline now applies
+  the scope in both forms. The README states that a failure returned
+  without `pipeline` should be built with the `failure` helper.
+
+## [0.7.0] - Macros::Policy::Check record-less policies; Sequencer i18n_scope applied at boundary
+
+### Changed (breaking)
+
+- **`Macros::Policy::Check#call` signature changed** from `(ctx, policy,
+  record_key, action)` to `(ctx, policy, action, record_key = nil)`.
+  `record_key` is now a trailing optional positional; omitting it
+  builds the policy with `nil` as the record, the shape required by
+  plural / collection policies (e.g. `Policies::Jobs`) that authorise
+  on a non-record subject rather than gating on a specific record:
+
+  ```ruby
+  # before
+  p.invoke(:check_policy, Policies::User, :user, :update)
+
+  # after
+  p.invoke(:check_policy, Policies::User, :update, :user)  # singular
+  p.invoke(:check_policy, Policies::Jobs, :list)           # record-less
+  ```
+
+  Migration: at every `p.invoke(:check_policy, ...)` call site, swap
+  the third and fourth positional arguments. Substitutes and the
+  underlying `policy.method_defined?(action)` typo-catch are
+  unchanged in behaviour; the parameter order on the substitute's
+  `call` is migrated to match.
+
+  See `docs/design.md` "Resolved Through Iteration" for the rationale
+  and the alternatives considered.
+
+### Added
+
+- **`Macros::Policy::Check.failure(ctx, policy, policy_result)`** class
+  helper. Returns `Result.failure(ctx, code: :forbidden, data: { policy:,
+  policy_result: })` — the same failure shape the macro produces. Lets
+  hand-rolled policy-check steps (for policy actions that take arguments,
+  or for compound logic the macro doesn't cover) produce the standard
+  failure shape without duplicating framework knowledge.
+
+- **`Macros::Policy::Check` now stores the built policy on `ctx[:policy]`.**
+  After building the policy instance and before invoking the action, the
+  macro writes it to ctx under `:policy` by default. Downstream steps (e.g.
+  contract construction that needs the policy injected) can read it
+  directly without re-building. Pass `as:` to store under a different key
+  when a sequencer runs multiple policy checks:
+
+  ```ruby
+  p.invoke(:check_policy, Policies::Document, :update, :document)
+  # ctx[:policy] is now the built Policies::Document instance
+
+  p.invoke(:check_policy, Policies::User, :show, :user, as: :user_policy)
+  # ctx[:user_policy] is the built Policies::User instance
+  ```
+
+  The substitute's `succeed_with` now accepts an optional policy instance;
+  passing one mirrors the production write to `ctx[as]` so substituted
+  specs can drive the same downstream paths.
+
+### Changed
+
+- **`Macros::Contract::Build`'s second parameter renamed** from
+  `attr_name` to `model`. The positional shape is unchanged — this is
+  an internal rename only — and the name now describes what the
+  parameter is (the ctx key/path for the model the contract wraps)
+  rather than what it isn't (an "attribute name" on anything). Callers
+  passing the value positionally (the only in-tree shape) are
+  unaffected.
+
+### Fixed
+
+- **`Sequencer#pipeline` and `Sequencer.()` now apply the sequencer's
+  auto-derived `i18n_scope` to the returned Result.** Closes a
+  documented-but-unimplemented step in the `Result#message`
+  translation fallback chain. Previously only `Sequencer#failure` (the
+  explicit helper) tagged a result with the sequencer's scope; macros
+  call `Result.failure` directly with no scope, so a sequencer body
+  that returned a macro's failure unchanged produced an unscoped
+  Result and `Result#message` fell through to the framework default
+  (`sequence.errors.<code>`) instead of the per-sequencer scoped
+  translation. Pure-macro sequencers (e.g. a body that's just
+  `pipeline(ctx) { |p| p.invoke(:check_policy, ...) }`) could never
+  produce a message translated under their own namespace. Tagging at
+  the boundary (`pipeline.result` and `Sequencer.()`) via
+  `Result#with_i18n_scope` preserves nested-sequencer "innermost scope
+  wins" semantics — `with_i18n_scope` is a no-op when the scope is
+  already set, so an inner sequencer's scope survives the outer
+  wrapper. See `docs/design.md` "Resolved Through Iteration" for the
+  rationale.
+
 ## [0.6.0] - Result.failure flat kwargs; Dispatch delegates reads and exposes raise helpers
 
 ### Changed (breaking)

data/README.md

@@ -126,7 +126,7 @@ class Seqs::UpdateUser
     pipeline(ctx) do |p|
       p.invoke(:find,           User,                  as: :user)
       p.invoke(:build_contract, Contracts::UpdateUser, :user)
-      p.invoke(:check_policy,   Policies::User,        :user, :update)
+      p.invoke(:check_policy,   Policies::User,        :update, :user)
 
       p.transaction do |t|
         t.invoke(:validate, from: %i[params user])
@@ -230,7 +230,7 @@ p.invoke(:build_contract, Contracts::CreateUser)         # no model
 
 | | |
 |---|---|
-| **Reads** | `ctx[attr_name]` for the model (optional) |
+| **Reads** | `ctx` at `model` for the model (optional) |
 | **Writes** | `ctx[:contract]` |
 | **Fails** | never |
 
@@ -288,20 +288,50 @@ Designed to work with the
 Builds a policy and calls the named action to authorise the operation.
 
 ```ruby
-p.invoke(:check_policy, Policies::User, :user, :update)
+p.invoke(:check_policy, Policies::User, :update, :user)  # policy on a record
+p.invoke(:check_policy, Policies::Jobs,  :list)          # plural / record-less
 ```
 
 The policy class must respond to `.build(current_user, record)`; the
 instance must respond to the action method and return a
 `Hubbado::Policy::Result`-shaped object (`permitted?`, `denied?`,
-`reason`, `message`).
+`reason`, `message`). When `record_key` is omitted the policy is built
+with `nil` as the record — the shape for plural / collection policies
+that authorise against a non-record subject (e.g. a company id read
+from `current_user`).
+
+The built policy instance is written to `ctx[:policy]` so downstream
+steps (e.g. contract construction that needs the policy injected) can
+read it directly. Pass `as:` to store under a different key when a
+sequencer runs more than one policy check:
+
+```ruby
+p.invoke(:check_policy, Policies::User, :show, :user, as: :user_policy)
+# ctx[:user_policy] — the built Policies::User instance
+```
 
 | | |
 |---|---|
-| **Reads** | `ctx[:current_user]`, `ctx[record_key]` |
-| **Writes** | nothing |
+| **Reads** | `ctx[:current_user]`, `ctx[record_key]` when `record_key` is supplied |
+| **Writes** | `ctx[as]` — the built policy instance (`as:` defaults to `:policy`) |
 | **Fails** | `:forbidden` when `permitted?` is false; `result.data` carries `{ policy:, policy_result: }` |
 
+The macro only covers zero-arg policy actions. For actions that take
+arguments (e.g. `Policies::Jobs#create(company_id)`), hand-roll a step
+and use `Macros::Policy::Check.failure(ctx, policy, policy_result)` to
+produce the standard failure shape:
+
+```ruby
+def check_create_policy(ctx)
+  policy = Policies::Jobs.build(ctx[:current_user], nil)
+  result = policy.create(ctx[:company_id])
+
+  return Macros::Policy::Check.failure(ctx, policy, result) unless result.permitted?
+
+  Result.success(ctx)
+end
+```
+
 A controller can branch on the denial reason via `data`:
 
 ```ruby
@@ -328,7 +358,7 @@ def call(ctx)
   pipeline(ctx) do |p|
     p.invoke(:find,           User,                  as: :user)
     p.invoke(:build_contract, Contracts::UpdateUser, :user)
-    p.invoke(:check_policy,   Policies::User,        :user, :update)
+    p.invoke(:check_policy,   Policies::User,        :update, :user)
 
     p.transaction do |t|
       t.invoke(:validate, from: %i[params user])
@@ -383,7 +413,7 @@ class Seqs::UpdateUser
       pipeline(ctx) do |p|
         p.invoke(:find,           User,                  as: :user)
         p.invoke(:build_contract, Contracts::UpdateUser, :user)
-        p.invoke(:check_policy,   Policies::User,        :user, :update)
+        p.invoke(:check_policy,   Policies::User,        :update, :user)
       end
     end
   end
@@ -474,6 +504,81 @@ with the sequencer's auto-derived i18n scope already applied. It takes
 the same kwargs as `Result.failure` (`code:`, `data:`, `step:`,
 `i18n_scope:`, `i18n_key:`, `i18n_args:`).
 
+## Translations
+
+`Result#message` translates the failure `code` through a fallback chain:
+
+1. **Per-error scope** — whatever the failure set as `i18n_scope:` (or
+   `i18n_key:` for an explicit key override).
+2. **Sequencer's auto-derived scope** — the class name underscored, with
+   `/` → `.`. `Seqs::UpdateUser` becomes `seqs.update_user`;
+   `Jobadder::Seqs::AuthorizationCallback` becomes
+   `jobadder.seqs.authorization_callback`.
+3. **Framework default** — `sequence.errors.<code>` (the gem ships
+   translations for the standard codes; see "Standard error codes" below).
+4. **Humanized code** — `:not_found` → `"Not found"`.
+
+The sequencer's scope is applied automatically. Both the `failure(ctx, ...)`
+helper *and* the boundary itself (the result of `pipeline(ctx)`, in block
+and chained form, and `Sequencer.()`) tag the returned `Result` with
+`i18n_scope` via `Result#with_i18n_scope`. That means an unscoped failure
+produced inside a macro, a hand-rolled step, or anywhere else in the
+pipeline picks up the sequencer's scope when the Result bubbles out — no
+`failure` call required.
+
+A sequencer that returns a failure without `pipeline` must build it with
+`failure(ctx, ...)`, not `Result.failure(...)`. An instance call (a test,
+or a nested sequencer run through `p.invoke`) reaches the sequencer's
+`call` directly, so only the helper gives that failure the sequencer's
+scope there.
+
+### Defining translations for a sequencer
+
+Drop translations under the sequencer's auto-derived scope in your locale
+file:
+
+```yaml
+en:
+  jobadder:
+    seqs:
+      authorization_callback:
+        forbidden: "You are not allowed to connect this company to JobAdder"
+        authorization_failed: "Could not authorize with JobAdder"
+```
+
+Now `result.message` returns the scoped string when the sequencer fails
+with `code: :forbidden` or `code: :authorization_failed`. Missing
+translations fall through to the framework default, then to the humanized
+code — so a fresh app gets sensible behaviour with zero config.
+
+### Per-error overrides
+
+A specific failure can override the scope or key. The error's own scope
+beats the sequencer's:
+
+```ruby
+failure(
+  ctx,
+  code: :not_shippable,
+  i18n_scope: "checkout.errors",  # used instead of seqs.place_order
+  i18n_key: :address_invalid,     # used instead of :not_shippable
+  i18n_args: { region: ctx[:country] }
+)
+```
+
+Resolves `checkout.errors.address_invalid` with the `%{region}`
+interpolation supplied.
+
+### Nested sequencers: innermost scope wins
+
+`Result#with_i18n_scope` is a no-op when the scope is already set, so a
+nested sequencer's scope sticks. If `UpdateUser` calls `Present` and
+Present's `Model::Find` macro fails, the failure is tagged with
+`seqs.present` first (Present's boundary); `UpdateUser`'s boundary tries
+to retag with `seqs.update_user` but the no-op preserves the inner scope.
+Messages resolve under the namespace of the sequencer that actually
+produced the failure, not the outermost wrapper.
+
 ## Outcome blocks and safety nets
 
 `run_sequence` enforces that serious failures are addressed. Forgetting to
@@ -530,6 +635,13 @@ as substitutes. Tests configure the substitutes for the scenario at hand.
 Substitutes default to pass-through `Result.success(ctx)` so a test only
 configures the ones whose return matters.
 
+An instance call takes a `Ctx`, the same strict ctx that the class-level
+`.()` builds for production, so a test passes one:
+`seq.(Hubbado::Sequence::Ctx.build(params: ..., current_user: ...))`.
+`pipeline` raises `ArgumentError` for keyword arguments or a plain Hash,
+because on a Hash a read of a missing key would return `nil` in the test
+and raise `KeyError` in production.
+
 ### Substituting macros directly
 
 ```ruby
@@ -541,7 +653,7 @@ context "Seqs::UpdateUser::Present happy path" do
   seq.find.succeed_with(user)
   seq.build_contract.succeed_with(contract)
 
-  result = seq.(params: { id: 1 }, current_user: User.new)
+  result = seq.(Hubbado::Sequence::Ctx.build(params: { id: 1 }, current_user: User.new))
 
   test "Is success" do
     assert(result.success?)
@@ -564,7 +676,7 @@ context "Seqs::UpdateUser::Present when the user is not found" do
   seq = Seqs::UpdateUser::Present.new
   seq.find.fail_with(code: :not_found)
 
-  result = seq.(params: { id: 999 }, current_user: User.new)
+  result = seq.(Hubbado::Sequence::Ctx.build(params: { id: 999 }, current_user: User.new))
 
   test "Fails with :not_found" do
     assert(result.code == :not_found)
@@ -605,8 +717,10 @@ context "Seqs::UpdateUser happy path" do
   seq.present.succeed_with(user: user, contract: contract)
 
   result = seq.(
-    params:       { user: { email: "new@example.com" } },
-    current_user: User.new
+    Hubbado::Sequence::Ctx.build(
+      params:       { user: { email: "new@example.com" } },
+      current_user: User.new
+    )
   )
 
   test "Is success" do
@@ -626,7 +740,7 @@ context "Seqs::UpdateUser when Present denies access" do
   seq = Seqs::UpdateUser.new
   seq.present.fail_with(code: :forbidden)
 
-  result = seq.(params: { user: {} }, current_user: User.new)
+  result = seq.(Hubbado::Sequence::Ctx.build(params: { user: {} }, current_user: User.new))
 
   test "Fails" do
     assert(result.failure?)
@@ -649,7 +763,7 @@ context "Seqs::UpdateUser when Present cannot find the record" do
   seq = Seqs::UpdateUser.new
   seq.present.fail_with(code: :not_found)
 
-  result = seq.(params: { id: 999, user: {} }, current_user: User.new)
+  result = seq.(Hubbado::Sequence::Ctx.build(params: { id: 999, user: {} }, current_user: User.new))
 
   test "Fails with :not_found" do
     assert(result.code == :not_found)

data/hubbado-sequence.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name = "hubbado-sequence"
-  s.version = "0.6.0"
+  s.version = "0.8.0"
   s.summary = "A small framework for the short sequences of common steps that controller actions usually boil down to"
   s.description = "A sequencer takes input, runs an ordered sequence of steps, and returns a Result carrying a success-or-failure flag, a structured error, and the working context that was built up during execution. Built with Rails in mind but framework-agnostic."
 

data/lib/hubbado/sequence/macros/contract/build.rb

@@ -10,9 +10,9 @@ module Hubbado
             new
           end
 
-          def call(ctx, contract_class, attr_name = nil)
-            model = attr_name && Path.resolve(ctx, attr_name)
-            ctx[:contract] = contract_class.new(model)
+          def call(ctx, contract_class, model = nil)
+            resolved_model = model && Path.resolve(ctx, model)
+            ctx[:contract] = contract_class.new(resolved_model)
             Result.success(ctx)
           end
 
@@ -30,7 +30,7 @@ module Hubbado
               self
             end
 
-            record def call(ctx, contract_class, attr_name = nil)
+            record def call(ctx, contract_class, model = nil)
               return Result.failure(ctx, **@configured_error) if @configured_error
 
               ctx[:contract] = @return_value if @configured_success

data/lib/hubbado/sequence/macros/policy/check.rb

@@ -10,29 +10,36 @@ module Hubbado
             new
           end
 
-          def call(ctx, policy, record_key, action)
+          def self.failure(ctx, policy, policy_result)
+            Result.failure(
+              ctx,
+              code: :forbidden,
+              data: { policy: policy, policy_result: policy_result }
+            )
+          end
+
+          def call(ctx, policy, action, record_key = nil, as: nil)
+            as ||= :policy
             current_user = ctx[:current_user]
-            record = ctx[record_key]
+            record = record_key && ctx[record_key]
 
             policy_instance = policy.build(current_user, record)
+            ctx[as] = policy_instance
             policy_result = policy_instance.public_send(action)
 
             if policy_result.permitted?
               Result.success(ctx)
             else
-              Result.failure(
-                ctx,
-                code: :forbidden,
-                data: { policy: policy_instance, policy_result: policy_result }
-              )
+              self.class.failure(ctx, policy_instance, policy_result)
             end
           end
 
           module Substitute
             include ::RecordInvocation
 
-            def succeed_with
+            def succeed_with(policy_instance = nil)
               @configured_success = true
+              @return_policy = policy_instance
               self
             end
 
@@ -41,7 +48,9 @@ module Hubbado
               self
             end
 
-            record def call(ctx, policy, record_key, action)
+            record def call(ctx, policy, action, record_key = nil, as: nil)
+              as ||= :policy
+
               unless policy.method_defined?(action)
                 raise ArgumentError,
                   "Macros::Policy::Check substitute: #{policy} does not declare action :#{action}"
@@ -49,6 +58,7 @@ module Hubbado
 
               return Result.failure(ctx, **@configured_error) if @configured_error
 
+              ctx[as] = @return_policy if @return_policy
               Result.success(ctx)
             end
 

data/lib/hubbado/sequence/pipeline.rb

@@ -4,11 +4,12 @@ module Hubbado
     # `pipeline(ctx)` helper. Not part of the public API — sequencers reach
     # it through the helper.
     class Pipeline
-      def initialize(ctx, dispatcher:)
+      def initialize(ctx, dispatcher:, i18n_scope: nil)
         @ctx = ctx
         @successful_steps = []
         @failed_result = nil
         @dispatcher = dispatcher
+        @i18n_scope = i18n_scope
       end
 
       # `step(:name)` dispatches to `dispatcher.send(name, ctx)`. The method
@@ -55,11 +56,9 @@ module Hubbado
       end
 
       def result
-        if @failed_result
-          @failed_result
-        else
-          Result.success(@ctx, successful_steps: @successful_steps.dup)
-        end
+        result = @failed_result || Result.success(@ctx, successful_steps: @successful_steps.dup)
+
+        result.with_i18n_scope(@i18n_scope)
       end
 
       private

data/lib/hubbado/sequence/sequencer.rb

@@ -62,7 +62,7 @@ module Hubbado
             ctx = Ctx.build(ctx)
           end
 
-          build.call(ctx)
+          build.call(ctx).with_i18n_scope(i18n_scope)
         end
 
         # Default factory: a sequencer with no configurable dependencies needs
@@ -95,8 +95,18 @@ module Hubbado
       # block, and returns the final Result — no trailing `.result` needed. The
       # non-block form returns the Pipeline so chained `.step(...)...result`
       # calls still work.
+      #
+      # Anything but a Ctx means an instance call skipped the Ctx that the
+      # class-level `.()` builds; run on a plain Hash, a missing key would
+      # read as nil rather than raise.
       def pipeline(ctx, &block)
-        pipe = Pipeline.new(ctx, dispatcher: self)
+        unless ctx.is_a?(Ctx)
+          raise ArgumentError,
+            "#{self.class.name}#pipeline expects a Hubbado::Sequence::Ctx, got #{ctx.class}; " \
+            "pass Hubbado::Sequence::Ctx.build(...) to an instance call"
+        end
+
+        pipe = Pipeline.new(ctx, dispatcher: self, i18n_scope: i18n_scope)
 
         if block
           block.call(pipe)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-sequence
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Hubbado Devs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: evt-casing