action_figure 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2f1def52c6601cb91ff3b2cd2fc366efeef932c1fba3072932f674cbf1748af
-  data.tar.gz: da5c9b0ab274f7e6f1512560af168d4d44c21dc3875ac85c0f79998902fa5df1
+  metadata.gz: d095409c73b40d8b3714b1e469e8edda371084844a277b486e5e06012453a301
+  data.tar.gz: 73a00b1d8003f3c17def805fa4e4cfabcf50ad52bf95f7df8fffa70e8ffdcefa
 SHA512:
-  metadata.gz: 1ebdc99c40beb7e461eab4022825efd657f15c29fc01a84d432f253928040ad1191057ed7c6b5845670d34af2963e56c9760aec613b590e577d81bae60da2233
-  data.tar.gz: d6b1112c59d61637c9e45e8f84b94ef25b75372e899b7f86e88ee0fc66d932325f567913ed75b47eb8283bde0a9d4e67935cbeac751665010b73cd56f1946cb9
+  metadata.gz: 2ed2a8b934e988503dcf41c07c3d39f3418e8b4c9e28f1ccbdb9fc7c8b709d7efa2d8141294f8cd8da8323f4b9f22d86f346fdc40010eb0d59e0872e476bf888
+  data.tar.gz: 65f498c906171ecbb98183700c0ae2c802fa1bbe3e09beb2ca69bb076eb308bd27f3999312e49fe10d18a5821383629f507be27a54f7f0451b9ab3ed2b27cded

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to ActionFigure will be documented in this file.
 
+## [0.7.0] - 2026-07-02
+
+### Added
+
+- **Central error-status registry.** `ActionFigure.error_statuses` lists every error helper (name → Rack status symbol); `ActionFigure.register_error(:BadGateway, :bad_gateway)` adds new ones. Generated helpers live on a registry module included into `ActionFigure::Formatter`, so a registered status is immediately available in **every** formatter, in action classes that were composed **before** the registration, and as `assert_*`/`refute_*`/`be_*` test helpers.
+- New built-in error statuses: **`Gone`** (410), **`Locked`** (423), and **`UnavailableForLegalReasons`** (451).
+- `ActionFigure.status_code_for(status_symbol)` — resolves a Rack status symbol to its numeric code (accepts both `:unprocessable_content` and `:unprocessable_entity` on every supported Rack version).
+- `register_error` validates its status symbol against Rack's status table and rejects helper names reserved by the formatter contract, so typos fail at boot instead of on the first rendered error.
+- `:rfc_9457` formatter implementing RFC 9457 Problem Details for HTTP APIs.
+  Errors render as `application/problem+json` with `type`, `title`, `status`,
+  `detail`, `instance`, and extension members. Success responses use the same
+  vocabulary (`type`, `title`, named resource key). Defaults derive from class
+  names and status symbols; all members accept override kwargs.
+- Generated error helpers now accept `errors: nil` (previously required) and
+  forward `**extras` to `error_response`. Existing formatters are unaffected
+  when called without extras.
+- **Contract assertions** — test an action's **`params_schema`**/**`rules`** in isolation, without invoking the action body. Minitest: **`assert_valid_params(action_class, params)`** and **`assert_invalid_params(action_class, params, on: :field)`**. RSpec: **`accept_params(params)`** and **`reject_params(params).with_error_on(:field)`** (subject is the action class). These are formatter-agnostic. Both raise a clear **`ArgumentError`** for actions without a **`params_schema`**.
+- **`assert_action_json`** / **`refute_action_json`** Minitest assertions — partial match on **`result[:json]`**, mirroring the RSpec **`have_action_json`** matcher. Nested Hashes match as subsets and **`Regexp`** values match against strings.
+- Negated Minitest status assertions: **`refute_Ok`**, **`refute_Created`**, … for every status (parity with RSpec **`not_to be_Ok`**).
+
+### Changed
+
+- **Formatter contract shrank from 8 methods to 4**: `Ok`, `Created`, `Accepted`, and the new `error_response(errors:, status:)`. Named error helpers (`NotFound`, `Conflict`, …) are generated from the registry and delegate to `error_response`; a hand-defined named helper on a formatter still wins.
+- The gem now declares a runtime dependency on **rack** (>= 2.2), used to resolve and validate status codes.
+- Status helpers for both adapters are now generated from the live registry (**`ActionFigure::Testing.statuses`**, including **`NoContent`**), so the Minitest and RSpec lists can no longer drift and newly registered statuses appear automatically. Replaces the RSpec-only **`ActionFigure::Testing::RSpec::MATCHERS`** constant.
+- Status assertions/matchers now fail with a clear "expected an ActionFigure result hash" message when given a non-Hash, instead of raising **`NoMethodError`**.
+
+### Removed
+
+- The deprecated `IndeterminantEntryPointError` alias (misspelled constant shipped through 0.6.0, aliased in 0.6.1). Use **`IndeterminateEntryPointError`**; update any remaining `rescue` clauses.
+
+### Known limitation
+
+- There is **no** formatter-agnostic assertion for **non-validation** error bodies (e.g. **`NotFound`**/**`Conflict`** with a custom **`errors:`** payload). Each formatter stores errors differently (**`json[:errors]`** vs **`json[:data]`** vs a JSON:API array) and the result hash carries no formatter identity. Assert those with a format-specific **`assert_action_json`** / **`have_action_json`**. Validation errors are best tested via the contract assertions above.
+
 ## [0.6.2] - 2026-06-25
 
 ### Fixed

data/README.md

@@ -130,13 +130,14 @@ Every action class has three responsibilities:
 | Feature | Description |
 |---------|-------------|
 | [Validation](docs/validation.md) | Two-layer validation powered by dry-validation: structural schemas with type coercion, plus validation rules. Includes cross-parameter helpers like `exclusive_rule`, `any_rule`, `one_rule`, and `all_rule`. |
-| [Response Formatters](docs/response-formatters.md) | Four built-in formats: Default, JSend, JSON:API, and Wrapped. Each provides response helpers (`Ok`, `Created`, `NotFound`, etc.) that return render-ready hashes. |
+| [Response Formatters](docs/response-formatters.md) | Five built-in formats: Default, JSend, JSON:API, Wrapped, and RFC 9457. Each provides response helpers (`Ok`, `Created`, `NotFound`, etc.) that return render-ready hashes. |
+| [Problem Details](docs/problem-details.md) | RFC 9457 formatter (`:rfc_9457`) that renders errors as `application/problem+json` problem documents with `type`, `title`, `status`, `detail`, and `instance` members. Success responses mirror the same vocabulary. |
 | [Status Codes](docs/status-codes.md) | Which 4xx codes are domain concerns (handled by action classes) vs perimeter concerns (handled by middleware, router, or infrastructure). |
 | [Custom Formatters](docs/custom-formatters.md) | Define your own response envelope by implementing the formatter interface. Registration validates your module at load time. |
 | [Actions](docs/actions.md) | Automatic entry point discovery, context injection via keyword arguments, per-class API versioning, and `entry_point` for disambiguation. |
 | [Configuration](docs/configuration.md) | Global defaults for response format, parameter strictness, and API version. All overridable per-class. |
 | [Notifications](docs/activesupport-notifications.md) | Opt-in `ActiveSupport::Notifications` events for every action call. Emits action class, outcome status, and duration on the `process.action_figure` event. |
-| [Testing](docs/testing.md) | Minitest assertions (`assert_Ok`, `assert_Created`, ...) and RSpec matchers (`be_Ok`, `be_Created`, ...) for expressive status checks. |
+| [Testing](docs/testing.md) | Status assertions/matchers (`assert_Ok`/`be_Ok`, ... plus negated `refute_Ok`), body matchers (`assert_action_json`/`have_action_json`), and formatter-agnostic contract assertions (`assert_valid_params`/`accept_params`, `assert_invalid_params`/`reject_params`). |
 | [Integration Patterns](docs/integration-patterns.md) | Recipes for serializers (Blueprinter, Alba, Oj Serializers), authorization (Pundit, CanCanCan), and pagination (cursor, Pagy). |
 
 ## Design Philosophy
@@ -191,7 +192,7 @@ Created(resource: user)
 
 # JSON:API
 Created(resource: user)
-# => { json: { data: { type: "users", id: "1", attributes: user } }, status: :created }
+# => { json: { data: { type: "user", id: "1", attributes: user } }, status: :created }
 
 # Wrapped
 Created(resource: user)

data/docs/custom-formatters.md

@@ -11,24 +11,23 @@ A formatter is a module that includes `ActionFigure::Formatter` and defines meth
 Including `ActionFigure::Formatter` gives you:
 
 - A default `NoContent` implementation that returns `{ status: :no_content }`.
-- A contract enforced at registration time: your module **must** define all 8 required methods.
+- Named error helpers for every registered error status (`NotFound`, `Conflict`, `Gone`, etc.), carried by a live registry module included into `ActionFigure::Formatter`. Each generated helper delegates to `error_response`.
+- A contract enforced at registration time: your module **must** define all 4 required methods.
 
 The required methods are:
 
-| Method                 | Purpose                                      |
-|------------------------|----------------------------------------------|
-| `Ok`                   | Successful retrieval or generic success      |
-| `Created`              | Resource was created                         |
-| `Accepted`             | Request accepted for background processing   |
-| `UnprocessableContent` | Validation or schema rule failure          |
-| `NotFound`             | Resource not found                           |
-| `Forbidden`            | Authorization failure                        |
-| `Conflict`             | Resource state conflict or duplicate         |
-| `PaymentRequired`      | Business billing or quota constraint         |
+| Method                 | Purpose                                                          |
+|------------------------|------------------------------------------------------------------|
+| `Ok`                   | Successful retrieval or generic success                          |
+| `Created`              | Resource was created                                             |
+| `Accepted`             | Request accepted for background processing                       |
+| `error_response`       | Low-level failure renderer called by every named error helper    |
 
 `NoContent` is provided by the base module and does not need to be defined, but you can override it if your format requires a different shape.
 
-Each method receives keyword arguments and must return a hash. The exact keywords depend on the outcome -- success methods receive `resource:` (and optionally `meta:`), while failure methods receive `errors:`.
+Named error helpers (`NotFound`, `Conflict`, `Gone`, `Locked`, `UnavailableForLegalReasons`, and any additional statuses you register) are generated from the error registry and all delegate to `error_response(errors:, status:, **extras)` — `errors:` is `nil` when the caller doesn't provide one, and any extra kwargs are forwarded. A formatter may still hand-define a specific named helper to override the generated one — a method defined on the formatter itself sits ahead of the generated helpers in the ancestor chain and wins.
+
+`error_response` receives the keyword arguments `errors:` (an error hash, or `nil`) and `status:` (a Rack status symbol), plus any pass-through kwargs the caller supplied, and must return a hash. See the contract update note under [Interface Validation](#interface-validation) for the recommended signature.
 
 ## Building a Custom Formatter
 
@@ -56,29 +55,13 @@ module WrappedFormatter
     { json: body, status: :accepted }
   end
 
-  def UnprocessableContent(errors:)
-    { json: { data: nil, errors: errors, status: "error" }, status: :unprocessable_content }
-  end
-
-  def NotFound(errors:)
-    { json: { data: nil, errors: errors, status: "error" }, status: :not_found }
-  end
-
-  def Forbidden(errors:)
-    { json: { data: nil, errors: errors, status: "error" }, status: :forbidden }
-  end
-
-  def Conflict(errors:)
-    { json: { data: nil, errors: errors, status: "error" }, status: :conflict }
-  end
-
-  def PaymentRequired(errors:)
-    { json: { data: nil, errors: errors, status: "error" }, status: :payment_required }
+  def error_response(errors:, status:)
+    { json: { data: nil, errors: errors, status: "error" }, status: status }
   end
 end
 ```
 
-All 8 required methods are defined. Success methods accept `resource:` and optionally `meta:`, while failure methods accept `errors:`. The `NoContent` method is inherited from the base `ActionFigure::Formatter` module and returns `{ status: :no_content }` with no JSON body -- override it if your format requires a different shape.
+All 4 required methods are defined. Success methods accept `resource:` and optionally `meta:`. `error_response` accepts `errors:` and `status:` and is called by every generated named error helper. The `NoContent` method is inherited from the base `ActionFigure::Formatter` module and returns `{ status: :no_content }` with no JSON body -- override it if your format requires a different shape.
 
 ## Registering Your Formatter
 
@@ -115,9 +98,13 @@ Registration is not just bookkeeping -- ActionFigure validates every formatter m
 
 ```ruby
 ActionFigure::Formatter::REQUIRED_METHODS
-# => [:Ok, :Created, :Accepted, :UnprocessableContent, :NotFound, :Forbidden, :Conflict, :PaymentRequired]
+# => [:Ok, :Created, :Accepted, :error_response]
 ```
 
+**Migration note (pre-0.7 formatters):** If you have a formatter written against the pre-0.7 eight-method contract that does not define `error_response`, registration will now **fail** — `REQUIRED_METHODS` requires `error_response`. Add an `error_response(errors:, status:)` method to your formatter before upgrading to 0.7.
+
+**`error_response` contract update (0.7+):** Generated error helpers now call `error_response` with `errors: nil` (previously `errors:` was required and always provided). If your formatter declares `error_response(errors:, status:)` strictly, it will continue to work for calls that pass `errors:`. However, if your formatter wants to support pass-through kwargs such as `detail:`, `instance:`, or custom extension members (as the `:rfc_9457` formatter does), declare the signature as `error_response(errors: nil, status:, **extras)` and forward `**extras` in your implementation. A strict formatter that declares only `(errors:, status:)` will raise `ArgumentError` when a caller passes extra kwargs — this is documented-correct behavior, not a bug. Only add `**extras` if your formatter intends to handle or forward those members.
+
 If any required method is missing, registration raises an `ArgumentError` that lists exactly which methods are absent:
 
 ```ruby
@@ -130,8 +117,7 @@ module IncompleteFormatter
 end
 
 ActionFigure.register_formatter(incomplete: IncompleteFormatter)
-# => ArgumentError: IncompleteFormatter is missing formatter methods: Created, Accepted,
-#    UnprocessableContent, NotFound, Forbidden, Conflict, PaymentRequired
+# => ArgumentError: IncompleteFormatter is missing formatter methods: Created, Accepted, error_response
 ```
 
 Validation is **atomic** when registering multiple formatters at once. If any single module in the batch fails validation, none of them are registered -- this ensures your registry always remains in a consistent state.
@@ -185,3 +171,17 @@ end
 ```
 
 Setting `config.format` makes every action use your formatter unless an individual action explicitly includes a different one. Per-action includes always take precedence over the global default.
+
+## Registering Additional Error Statuses
+
+ActionFigure ships with eight built-in error statuses (see [HTTP 4xx Status Codes](status-codes.md)). You can register additional ones with `ActionFigure.register_error`:
+
+```ruby
+ActionFigure.register_error(:BadGateway, :bad_gateway)
+```
+
+The first argument is the helper name (a Symbol or String) that will be available in action classes (`BadGateway(errors:)`). The second argument must be a valid Rack status symbol — `register_error` validates it against `Rack::Utils::SYMBOL_TO_STATUS_CODE` and raises `ArgumentError` immediately for a symbol no supported Rack version knows, so a typo fails at boot rather than on the first error rendered in production.
+
+Registration is **add-only**: you cannot remove or override a built-in status. Names reserved by the formatter contract (`Ok`, `Created`, `Accepted`, `NoContent`, `error_response`) are rejected.
+
+Registration can happen at any time. Generated helpers live on a single registry module included into `ActionFigure::Formatter`, so a newly registered status is immediately available to every formatter and every action class — including classes that ran `include ActionFigure[...]` before the registration — and `register_error` also patches any already-loaded Minitest assertions and RSpec matchers. An initializer is still the natural home for registrations, but nothing breaks if one runs late.

data/docs/integration-patterns.md

@@ -188,14 +188,14 @@ end
 
 ## Authorization
 
-Authorization gems work naturally with action classes. Inject the current user from the controller and call the authorization check during orchestration.
+Authorization gems work naturally with action classes. Inject the authorization context from the controller -- the current user for Pundit, the current ability for CanCanCan -- and run the check during orchestration.
 
 ### Pundit
 
-Call the [Pundit](https://github.com/varvet/pundit) policy directly inside the action:
+Let [Pundit](https://github.com/varvet/pundit) infer the policy from the record with `Pundit.policy!`, then call the query. It returns a plain boolean, so a denial flows through your formatter as a `Forbidden` response -- no `rescue_from`, no exceptions:
 
 ```ruby
-class Users::DestroyAction
+class Projects::DestroyAction
   include ActionFigure[:jsend]
 
   params_schema do
@@ -203,52 +203,54 @@ class Users::DestroyAction
   end
 
   def call(params:, current_user:)
-    user = User.find(params[:id])
-    unless UserPolicy.new(current_user, user).destroy?
-      return Forbidden(errors: { base: ["not authorized to delete this user"] })
+    project = Project.find(params[:id])
+    unless Pundit.policy!(current_user, project).destroy?
+      return Forbidden(errors: { base: ["not authorized to delete this project"] })
     end
-    user.destroy!
+    project.destroy!
     NoContent()
   end
 end
 ```
 
 ```ruby
-class UsersController < ApplicationController
+class ProjectsController < ApplicationController
   def destroy
-    render Users::DestroyAction.call(params:, current_user: current_user)
+    render Projects::DestroyAction.call(params:, current_user: current_user)
   end
 end
 ```
 
+`Pundit.policy!(current_user, project)` does the same policy-class lookup as a controller (`project` → `ProjectPolicy`); you name the query (`:destroy?`) explicitly, since an action class has no controller `action_name` to infer it from.
+
 ### CanCanCan
 
-With [CanCanCan](https://github.com/CanCanCommunity/cancancan), build the ability from the current user:
+With [CanCanCan](https://github.com/CanCanCommunity/cancancan), inject the controller's `current_ability` and consult it directly. CanCanCan's `can?` and `authorize!` helpers already delegate to `current_ability`, so passing the ability keeps the action idiomatic and decoupled from how the ability is built:
 
 ```ruby
-class Users::DestroyAction
+class Projects::DestroyAction
   include ActionFigure[:jsend]
 
   params_schema do
     required(:id).filled(:integer)
   end
 
-  def call(params:, current_user:)
-    user = User.find(params[:id])
-    if Ability.new(current_user).can?(:destroy, user)
-      user.destroy!
+  def call(params:, current_ability:)
+    project = Project.find(params[:id])
+    if current_ability.can?(:destroy, project)
+      project.destroy!
       NoContent()
     else
-      Forbidden(errors: { base: ["not authorized to delete this user"] })
+      Forbidden(errors: { base: ["not authorized to delete this project"] })
     end
   end
 end
 ```
 
 ```ruby
-class UsersController < ApplicationController
+class ProjectsController < ApplicationController
   def destroy
-    render Users::DestroyAction.call(params:, current_user: current_user)
+    render Projects::DestroyAction.call(params:, current_ability:)
   end
 end
 ```

data/docs/problem-details.md

@@ -0,0 +1,113 @@
+# Problem Details (RFC 9457)
+
+## Overview
+
+The `:rfc_9457` formatter renders errors as [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents with `Content-Type: application/problem+json`. Success responses mirror the same `type`/`title` vocabulary, though RFC 9457 itself only specifies error documents.
+
+```ruby
+class Projects::FindAction
+  include ActionFigure[:rfc_9457]
+
+  def show(params:)
+    project = Project.find_by(id: params[:id])
+    return NotFound(
+      errors: { id: ["not found"] },
+      type: "https://api.example.com/problems/project-not-found",
+      title: "Project not found",
+      detail: "No project with id #{params[:id]} exists.",
+      instance: "/projects/#{params[:id]}"
+    ) unless project
+
+    Ok(resource: project, type: "project-found", title: "Project found")
+  end
+end
+```
+
+## Error Responses
+
+Error helpers (`NotFound`, `Conflict`, etc.) produce a problem document:
+
+| Member     | Default                                                    | Override kwarg |
+|------------|------------------------------------------------------------|----------------|
+| `type`     | `"<action-class>-<status>-error"`; `UnprocessableContent` uses `"unprocessable-content-error"` (see Defaults below) | `type:` |
+| `title`    | HTTP status phrase, e.g. `"Not Found"`                     | `title:`       |
+| `status`   | Numeric HTTP code, e.g. `404`                              | —              |
+| `detail`   | Omitted                                                    | `detail:`      |
+| `instance` | Omitted                                                    | `instance:`    |
+| `errors`   | Extension member; omitted when nil                         | `errors:`      |
+
+Any additional kwargs become extension members.
+
+The render hash includes `content_type: "application/problem+json"`. Rails honors this directly; a plain Rack app can read the key.
+
+### Defaults
+
+`UnprocessableContent` has a fixed default type of `"unprocessable-content-error"`. The framework calls this helper automatically on schema validation failure, so a stable type is provided without configuration:
+
+```ruby
+# Schema failure — type is already "unprocessable-content-error":
+UnprocessableContent(errors: result.errors.to_h)
+
+# Override when you want a domain-specific URI:
+UnprocessableContent(
+  errors: user.errors.messages,
+  type: "https://api.example.com/problems/validation-error",
+  title: "Validation failed"
+)
+```
+
+All other error helpers derive `type` mechanically from the action class and HTTP status — `Projects::FindAction` + `NotFound` → `"projects-find-not-found-error"`. This is intentionally awkward. The RFC recommends a stable URI, and your API clients deserve one:
+
+```ruby
+# Awkward default — a signal to replace it:
+# type: "projects-find-not-found-error"
+
+# What you should write instead:
+NotFound(
+  type: "https://api.example.com/problems/project-not-found",
+  title: "Project not found",
+  errors: { id: ["not found"] }
+)
+```
+
+## Success Responses
+
+Success helpers (`Ok`, `Created`, `Accepted`) build a mirrored vocabulary:
+
+| Member            | Default                                            | Override kwarg |
+|-------------------|----------------------------------------------------|----------------|
+| `type`            | `"<resource-name>-<status>"` (see below)           | `type:`        |
+| `title`           | `"<Resource name> <status>"` (see below)           | `title:`       |
+| `<resource-key>`  | Resource under its class-derived name or `data`    | `as:`          |
+| `meta`            | Omitted when nil                                   | `meta:`        |
+
+The resource key and name derive from the resource's class:
+
+```ruby
+Created(resource: user)       # User instance → key :user
+# type: "user-created", title: "User created", user: { ... }
+
+Created(resource: some_hash)  # Hash → key :data
+# type: "resource-created", title: "Resource created", data: { ... }
+
+Created(resource: h, as: :project)  # explicit override
+# type: "project-created", title: "Project created", project: { ... }
+```
+
+`as:`, `type:`, and `title:` can be used independently — `as:` drives the resource key and the derived defaults; `type:` and `title:` override only their own member.
+
+Trailing `Action` is stripped from class names: `Projects::CreateAction` → `"projects-create"`.
+
+`Ok(resource: user)` defaults to `type: "user-ok"` / `title: "User ok"` — deliberately awkward for the same reason as error defaults. Pass `type:` and `title:` to give your clients something meaningful.
+
+Success responses use plain `application/json` (no `content_type:` key).
+
+`NoContent` returns `{ status: :no_content }` with no body — inherited from the base formatter.
+
+## Registering Additional Error Statuses
+
+`ActionFigure.register_error` works the same way as with any other formatter. Registered error helpers automatically use `error_response`, so they produce problem documents in `:rfc_9457` action classes without any extra configuration.
+
+## Custom `error_response` Contract
+
+If you write a custom formatter that you want to compose with RFC 9457 style, note that `error_response` now receives `errors: nil, status:, **extras`. Accept `**extras` to let `detail:`, `instance:`, and extension members flow through.