hubbado-sequence 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc373389ca48751e5d60ebc84c00dfd8740b437ec89a53b8d9a1b986ea5c2a48
-  data.tar.gz: 7053947aa597354f5b973832083ebc8cc9e60e4de3a1cee23524045f803a63cd
+  metadata.gz: 4c072f343cb764529d76c7babb7824217546cadeaf4cab59c305b40b0b1f7647
+  data.tar.gz: 15c860841338562d2ba8b39c8d49d1a95959345eec316489878676a0b9f4a3e4
 SHA512:
-  metadata.gz: 240dbbf380bea6a9007872456c97d052a6cedf0f5b716fbffe63876362f7c66f89f18accbf51d1cd99f2ee0f3f377376c7161770e46d85f6314548bc07d6549b
-  data.tar.gz: ef08b3226afc5465ecac7030ca8e36ad9c3a2ecb967530144bb96aad79a670e2085eda9e74d80b4cc05e4617deab78ac0903150ff5ed6b78f4cf1b58a912d778
+  metadata.gz: 414d6011c8b468686ba3fe6f93adfa119d16196b25cc3313073463a56673aaf5a51100cb2b21ecd96e471511b4954cff6bbfd7e14806fc2c9370ac7c40a40020
+  data.tar.gz: df9d8e8d1c8ce2715f7b8582de9ed6a51106f5ff0f6c99caf596d9fb0f8b4ec5dc0818fecf01cb92149aa13f9813c40b7221b4cdcb1604d9a8ef3b0f43e037db

data/CHANGELOG.md

@@ -4,6 +4,94 @@ 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.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,74 @@ 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 (`Sequencer#pipeline` 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 sequencer body picks up the sequencer's
+scope when the Result bubbles out — no `failure` call required.
+
+### 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

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.7.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/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
@@ -100,7 +100,7 @@ module Hubbado
 
         if block
           block.call(pipe)
-          pipe.result
+          pipe.result.with_i18n_scope(i18n_scope)
         else
           pipe
         end

metadata

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