action_figure 0.5.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2afc60d26a2b7f19aa7a5e8e1e438dba5f0400688c9dd0b5ec184f0307484366
-  data.tar.gz: 346713da33afd14d6ea9d7862fbd7e71030d116e467664d6c73f19397e9a54c0
+  metadata.gz: f2f1def52c6601cb91ff3b2cd2fc366efeef932c1fba3072932f674cbf1748af
+  data.tar.gz: da5c9b0ab274f7e6f1512560af168d4d44c21dc3875ac85c0f79998902fa5df1
 SHA512:
-  metadata.gz: 2dba3a5b85d8f8bd55ebcfca08fb9eeedb508e2ff2d5f16cd8c971c0e3eb5586ab614922b341c90aaed4ad4e3607eefd71c7bd76e881592b45f5a1ac4688e9f8
-  data.tar.gz: 9a796394dc06f986ec4cbeef0e7e9cf3e3a9a80aaa15b51edb16201e89db815e86f8ccc3b816366543c7a8878327fd8f2be9fee11a4fbfe4adc47fade36e3879
+  metadata.gz: 1ebdc99c40beb7e461eab4022825efd657f15c29fc01a84d432f253928040ad1191057ed7c6b5845670d34af2963e56c9760aec613b590e577d81bae60da2233
+  data.tar.gz: d6b1112c59d61637c9e45e8f84b94ef25b75372e899b7f86e88ee0fc66d932325f567913ed75b47eb8283bde0a9d4e67935cbeac751665010b73cd56f1946cb9

data/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to ActionFigure will be documented in this file.
+
+## [0.6.2] - 2026-06-25
+
+### Fixed
+
+- Without a **`params_schema`**, params now pass through **untouched** — **`to_unsafe_h`** is only called when there is a schema to validate against. Previously an **`ActionController::Parameters`** (or any object responding to **`to_unsafe_h`**) was unwrapped into a plain hash even with no schema, contradicting the 0.6.0 "no schema → params pass through unvalidated" contract. **Breaking** for code that relied on the implicit unwrap; such actions should unwrap (e.g. via strong params) themselves.
+
+### Documentation
+
+- **`README.md`**: simplify the before/after hint that prompts readers to spot the incorrect render response.
+
+## [0.6.1] - 2026-05-23
+
+### Added
+
+- **`have_action_json`** RSpec matcher (partial match on **`result[:json]`** via **`a_hash_including`**).
+- Notifications payload **`entry_point`** (Symbol) alongside **`action`** for **`process.action_figure`**.
+- **`InitializationNotSupportedError`** when an action class defines **`initialize`** (instances are built with arity-zero **`new`**).
+- CI job running **`bundle exec rbs validate`**.
+- Regression test asserting built-in formatters expose **`Formatter::REQUIRED_METHODS`** (+ **`NoContent`**).
+
+### Changed
+
+- Renamed `IndeterminantEntryPointError` → **`IndeterminateEntryPointError`** (raised when multiple public entry methods exist without `entry_point`). The old constant remains as a deprecated alias (`Module#deprecate_constant`) for one release; update any `rescue` clauses to the new spelling.
+- **`params_schema`** may only be called once per action class; a duplicate call raises **`ArgumentError`** (previously enforced only when a **`rules`** block was already present).
+
+### Documentation
+
+- Load-order semantics for **`ActionFigure.configure`** (default **`format`** and **`activesupport_notifications`** latch when each class **`include`** runs).
+- Testing guide: matchers/assertions inspect **`[:status]`** only; RSpec **`require`** order.
+- Actions guide: mermaid overview of **`method_added`** / **`entry_point`** discovery.
+- Actions guide: do not define **`initialize`** on actions (arity-zero **`new`**); use **`InitializationNotSupportedError`** when violated.
+- Actions guide: **`api_version`** — clarify global (**`configure`**) vs class macro (**no fallback**).
+- **`README.md`**: `:unprocessable_entity` vs ActionFigure **`result[:status]`** symbol **`:unprocessable_content`**.
+- Configuration guide: **thread safety** / singleton **`ActionFigure.configuration`** semantics.
+- ActiveSupport Notifications: payload documents **`entry_point`**; subscriber examples reference it.
+- Testing guide: **`have_action_json`** RSpec matcher.
+
+## [0.6.0] - 2026-03-30
+
+### Added
+
+- `Conflict` (409) and `PaymentRequired` (402) response helpers across all formatters
+- Automatic entry point discovery via `method_added` — single public method is detected without needing `entry_point`
+- `IndeterminantEntryPointError` raised when multiple public methods exist without an explicit `entry_point`
+- Status codes documentation (`docs/status-codes.md`)
+
+### Changed
+
+- `params_schema` is now optional — actions without a schema pass `params:` through unvalidated
+
+## [0.5.0] - 2026-03-25
+
+### Added
+
+- Thread-safe format registry using `Concurrent::Map`
+- RBS type signatures for the full public API (`sig/action_figure.rbs`)
+- Integration test suite (`test/integration/full_pipeline_test.rb`)
+
+### Fixed
+
+- Schema guard: redefining `params_schema` after `rules` now raises instead of silently dropping rules
+- Keyword argument safety: non-params kwargs pass through untouched
+- Consistent envelope: `Accepted` without a resource uses `nil` data (not omitted key) in Default and Wrapped formatters
+- RSpec negated matcher failure message now shows actual status
+
+## [0.4.0] - 2026-03-21
+
+### Added
+
+- Wrapped formatter (`ActionFigure::Formatters::Wrapped`) with uniform `{ data:, errors:, status: }` envelope
+- Default formatter (`ActionFigure::Formatters::Default`) with `{ data: }` envelope
+- `ActiveSupport::Notifications` instrumentation (opt-in via `activesupport_notifications` config)
+- Cross-parameter rule helpers: `exclusive_rule`, `any_rule`, `one_rule`, `all_rule`
+- `meta:` keyword on success response helpers (`Ok`, `Created`, `Accepted`)
+- `.contract` accessor for standalone schema/rules introspection
+- `api_version` class-level macro for per-action version tagging
+- `whiny_extra_params` configuration option
+- Minitest assertions (`assert_Ok`, `assert_Created`, etc.) and RSpec matchers (`be_Ok`, `be_Created`, etc.)
+- JSON:API formatter with `Resource` serializer for ActiveRecord objects
+- Custom formatter registration with load-time validation
+- User-facing documentation for all features
+
+### Changed
+
+- `UnprocessableEntity` renamed to `UnprocessableContent` to match Rails 7.1+ naming
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Initial release
+- Core validation pipeline powered by dry-validation
+- JSend response formatter
+- `params_schema` and `rules` DSL
+- `ActionController::Parameters` support via `to_unsafe_h`
+- `NoContent` response helper

data/README.md

@@ -5,264 +5,245 @@ Fully-articulated controller actions.
 ---
 > #### Table of Contents
 > [Installation](#installation)<br>
-> [Quick Start](#quick-start)<br>
 > [How It Works](#how-it-works)<br>
 > [Features](#features)<br>
-> [Full Example](#full-example)<br>
 > [Design Philosophy](#design-philosophy)<br>
+> [Examples](#examples)<br>
 > [Requirements](#requirements)<br>
 > [License](#license)
 ---
 
-**ActionFigure** replaces gnarly controller method logic with explicit, purpose-driven operation classes. Each action validates its input, executes its logic, and returns a render-ready hash — making your controller action methods one-liners and behavior easily testable.
+**ActionFigure** makes your controller actions more usable and understandable. It turns this:
 
-## Installation
+```ruby
+class ProjectsController < ApplicationController
+  def create
+    permitted = params.require(:project).permit(
+      :name, :description, settings: [:visibility, :notify_on_mention]
+    )
 
-Add to your Gemfile and `bundle install`:
+    if permitted[:name].blank?
+      render json: { status: "fail", data: { name: ["is required"] } },
+             status: :unprocessable_entity
+      return
+    end
 
-```ruby
-gem "action_figure"
-```
+    if permitted.dig(:settings, :visibility).present? &&
+       !%w[public private].include?(permitted[:settings][:visibility])
+      render json: { status: "fail", data: { settings: { visibility: ["must be public or private"] } } },
+             status: :unprocessable_entity
+      return
+    end
 
-## Quick Start
+    unless current_user.member_of?(current_workspace)
+      render json: { status: "fail", data: { base: ["must be a workspace member"] } },
+             status: :forbidden
+      return
+    end
 
-**1. Start with what the action should do.**
+    if current_workspace.projects.exists?(name: permitted[:name])
+      render json: { status: "fail", data: { name: ["already exists in this workspace"] } },
+             status: :conflict
+      return
+    end
 
-```ruby
-# spec/actions/users/create_action_spec.rb
-RSpec.describe Users::CreateAction do
-  it "creates a user with valid parameters" do
-    company = Company.create!(name: "Acme")
-
-    # Note: Extra keyword arguments like company: are injected as context alongside params:
-    result = Users::CreateAction.call(
-      params: { user: { name: "Tad", email: "tad@example.com" } },
-      company: company
-    )
+    project = CreateProject.run(permitted, workspace: current_workspace, creator: current_user)
 
-    # Results are render-ready hashes (JSend formatted in this case)
-    # => { json: { status: "success", data: { name: "Tad", ... } }, status: :created }
-    expect(result).to be_Created
-    expect(result[:json][:data]).to include("name" => "Tad", "email" => "tad@example.com")
-    expect(User.find_by(email: "tad@example.com")).to be_persisted
+    if project.errors.any?
+      render json: { status: "fail", data: project.errors.messages },
+             status: :unprocessable_entity
+      return
+    end
+
+    render json: { status: "success", data: ProjectBlueprint.render_as_hash(project) }
   end
+end
+```
 
-  it "fails when name is missing" do
-    company = Company.create!(name: "Acme")
-    result = Users::CreateAction.call(
-      params: { user: { email: "tad@example.com" } },
-      company: company
-    )
+into this:
 
-    # Validation failures short-circuit before #call executes
-    # => { json: { status: "fail", data: { user: { name: ["is missing"] } } },
-    #      status: :unprocessable_content }
-    expect(result).to be_UnprocessableContent
-    expect(result[:json][:data][:user][:name]).to include("is missing")
-    expect(User.find_by(email: "tad@example.com")).not_to be_persisted
+```ruby
+class ProjectsController < ApplicationController
+  def create
+    render Projects::CreateAction.create(params:, current_user:, current_workspace:)
   end
 end
 ```
 
-**2. Define the action class.**
-
 ```ruby
-# app/actions/users/create_action.rb
-class Users::CreateAction
+class Projects::CreateAction
   include ActionFigure[:jsend]
 
   params_schema do
-    required(:user).hash do
+    required(:project).hash do
       required(:name).filled(:string)
-      required(:email).filled(:string)
+      optional(:description).filled(:string)
+      optional(:settings).hash do
+        optional(:visibility).filled(:string, included_in?: %w[public private])
+        optional(:notify_on_mention).filled(:bool)
+      end
     end
   end
 
-  def call(params:, company:)
-    user = company.users.create(params[:user])
-    return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
+  def create(params:, current_user:, current_workspace:)
+    unless current_user.member_of?(current_workspace)
+      return Forbidden(errors: { base: ["must be a workspace member"] })
+    end
+
+    if current_workspace.projects.exists?(name: params[:project][:name])
+      return Conflict(errors: { name: ["already exists in this workspace"] })
+    end
+
+    project = CreateProject.run(params[:project], workspace: current_workspace, creator: current_user)
+    return UnprocessableContent(errors: project.errors.messages) if project.errors.any?
 
-    Created(resource: user.as_json(only: %i[id name email]))
+    Created(resource: ProjectBlueprint.render_as_hash(project))
   end
 end
 ```
 
-**3. Call it from your controller.**
+- The shape and types of your params are obvious
+- The structure is clear
+- The tests are easy (and 10x faster)
+- The responses are uniform and render-ready
+
+(Look closely, one of the responses in the first example is wrong. Can you spot it?)
+
+## Installation
+
+Add to your Gemfile and `bundle install`:
 
 ```ruby
-class UsersController < ApplicationController
-  def create
-    render Users::CreateAction.call(params:, company: current_company)
-  end
-end
+gem "action_figure"
 ```
 
 ## How It Works
 
 Every action class has three responsibilities:
 
-1. **Check params** — `params_schema` validates structure and types, `rules` enforces validation rules. If either fails, the formatter returns an error response and `#call` is never invoked.
-2. **Orchestrate** — `#call` coordinates the work: creating records, calling service objects, enqueuing jobs, or anything else your operation requires. The action is the entry point, not necessarily where all the logic lives.
+1. **Check params** (optional) — when a `params_schema` is defined, it validates structure and types; `rules` enforces validation rules. If either fails, the formatter returns an error response and your action method is never invoked. Actions without a schema receive `params:` as-is.
+2. **Orchestrate** — your action method coordinates the work: creating records, coordinating collaborators, enqueuing jobs, or anything else the action requires. The action is the entry point, not necessarily where all the logic lives.
 3. **Return a formatted response** — response helpers like `Created(resource:)` and `NotFound(errors:)` return render-ready hashes that go straight to `render` in your controller.
 
 ## Features
 
 | 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 `one_rule`, `all_rule`, and `implies_rule`. |
+| [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. |
+| [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) | Custom entry points (`entry_point :search`), context injection via keyword arguments, per-class API versioning, and no-params actions. |
+| [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. |
 | [Integration Patterns](docs/integration-patterns.md) | Recipes for serializers (Blueprinter, Alba, Oj Serializers), authorization (Pundit, CanCanCan), and pagination (cursor, Pagy). |
 
-## Full Example
+## Design Philosophy
+
+ActionFigure is scoped to controller actions — it validates params, runs your logic, and returns a hash you pass directly to `render`.
+
+- **Purpose over convention** — each class does one thing and names it clearly
+- **Explicit over implicit** — no magic method resolution, no inherited callbacks
+- **Actions own their lifecycle** — validation, execution, and response formatting live together
+- **Controllers become boring** — one-line `render` calls that delegate to action classes
+- **Separate domain tests from perimeter tests** — keep your controller tests for perimeter checks, but now your domain logic lives in plain method calls. Faster tests, clearer failures.
 
-Here is a more complete action showing how validation, authorization, and response formatting work together.
+## Examples
 
-**The action class:**
+### Validation Rules
+
+Cross-parameter helpers make multi-field constraints declarative:
 
 ```ruby
-# app/actions/orders/create_action.rb
-class Orders::CreateAction
-  include ActionFigure[:wrapped]
+class Search::LookupAction
+  include ActionFigure[:jsend]
 
   params_schema do
-    required(:item_id).filled(:integer)
-    required(:quantity).filled(:integer)
-    optional(:coupon_code).filled(:string)
-    optional(:gift_message).filled(:string)
-    optional(:gift_recipient_email).filled(:string)
+    optional(:user_id).filled(:integer)
+    optional(:email).filled(:string)
   end
 
   rules do
-    all_rule(:gift_message, :gift_recipient_email,
-             "gift fields must be provided together or not at all")
+    exclusive_rule(:user_id, :email, "provide one, not both")
   end
 
-  def call(params:, current_user:)
-    if current_user.unpaid_balance?
-      return Forbidden(errors: { base: ["unpaid balance on account"] })
-    end
-
-    item = Item.find_by(id: params[:item_id])
-    return NotFound(errors: { item_id: ["item not found"] }) unless item
+  def lookup(params:)
+    user = params[:user_id] ? User.find_by(id: params[:user_id]) : User.find_by(email: params[:email])
 
-    order = current_user.orders.create(
-      item: item,
-      quantity: params[:quantity],
-      coupon_code: params[:coupon_code]
-    )
-    return UnprocessableContent(errors: order.errors.messages) if order.errors.any?
-
-    resource = OrderBlueprint.render_as_hash(order, view: :confirmation)
-    Created(resource:)
+    Ok(resource: user.as_json)
   end
 end
 ```
 
-**The controller:**
+### Response Formatters
 
-```ruby
-class OrdersController < ApplicationController
-  def create
-    render Orders::CreateAction.call(params:, current_user:)
-  end
-end
-```
-
-**Testing it:**
+Choose a response envelope by name. The same helpers return different shapes:
 
 ```ruby
-# test/actions/orders/create_action_test.rb
-require "action_figure/testing/minitest"
+# Default
+Created(resource: user)
+# => { json: { data: user }, status: :created }
 
-class Orders::CreateActionTest < Minitest::Test
-  include ActionFigure::Testing::Minitest
-
-  def test_creates_an_order
-    user = User.create!(name: "Tad")
-    item = Item.create!(name: "Widget", price: 29.00)
-
-    result = Orders::CreateAction.call(
-      params: { item_id: item.id, quantity: 2 },
-      current_user: user
-    )
+# JSend
+Created(resource: user)
+# => { json: { status: "success", data: user }, status: :created }
 
-    assert_Created(result)
-    assert_equal item.id, result[:json][:data]["item_id"]
-    assert_equal 2, result[:json][:data]["quantity"]
-  end
+# JSON:API
+Created(resource: user)
+# => { json: { data: { type: "users", id: "1", attributes: user } }, status: :created }
 
-  def test_forbidden_with_unpaid_balance
-    user = User.create!(name: "Tud", balance: -1)
+# Wrapped
+Created(resource: user)
+# => { json: { data: user, errors: nil, status: "success" }, status: :created }
+```
 
-    result = Orders::CreateAction.call(
-      params: { item_id: 1, quantity: 1 },
-      current_user: user
-    )
+### Testing
 
-    assert_Forbidden(result)
-    assert_includes result[:json][:errors][:base], "unpaid balance on account"
-  end
+Action classes are plain method calls — no request setup needed:
 
-  def test_not_found_when_item_missing
-    user = User.create!(name: "Tad")
+```ruby
+class Search::LookupActionTest < Minitest::Test
+  include ActionFigure::Testing::Minitest
 
-    result = Orders::CreateAction.call(
-      params: { item_id: 999, quantity: 1 },
-      current_user: user
+  def test_finds_by_email
+    result = Search::LookupAction.lookup(
+      params: { email: "tad@example.com" }
     )
 
-    assert_NotFound(result)
-    assert_includes result[:json][:errors][:item_id], "item not found"
+    assert_Ok(result)
   end
 
-  def test_surfaces_model_validation_errors
-    user = User.create!(name: "Tad")
-    item = Item.create!(name: "Widget", price: 29.00, stock: 0)
-
-    result = Orders::CreateAction.call(
-      params: { item_id: item.id, quantity: 5 },
-      current_user: user
+  def test_rejects_both_user_id_and_email
+    result = Search::LookupAction.lookup(
+      params: { user_id: 1, email: "tad@example.com" }
     )
 
     assert_UnprocessableContent(result)
-    assert_includes result[:json][:errors][:quantity], "exceeds available stock"
+    assert_includes result[:json][:data][:user_id], "provide one, not both"
   end
+end
+```
 
-  def test_rejects_partial_gift_fields
-    user = User.create!(name: "Tad")
-    item = Item.create!(name: "Widget", price: 29.00)
+### Actions Without a Schema
 
-    result = Orders::CreateAction.call(
-      params: { item_id: item.id, quantity: 1, gift_message: "Enjoy!" },
-      current_user: user
-    )
+Not every action needs parameter validation:
 
-    assert_UnprocessableContent(result)
-    assert_includes result[:json][:errors][:gift_message],
-                    "gift fields must be provided together or not at all"
-    assert_includes result[:json][:errors][:gift_recipient_email],
-                    "gift fields must be provided together or not at all"
+```ruby
+class HealthCheckAction
+  # Uses the globally-configured format
+  include ActionFigure
+
+  def check(current_user:)
+    Ok(resource: { status: "healthy", user: current_user.name })
   end
 end
 ```
 
-## Design Philosophy
-
-- **Purpose over convention** — each class does one thing and names it clearly
-- **Explicit over implicit** — no magic method resolution, no inherited callbacks
-- **Operations own their lifecycle** — validation, execution, and response formatting live together
-- **Controllers become boring** — one-line `render` calls that delegate to action classes
-- **Models and Controllers stay thin** — business logic moves to purpose-built operations
-
 ## Requirements
 
 - Ruby >= 3.2
-- [dry-validation](https://dry-rb.org/gems/dry-validation/) ~> 1.10
+- [dry-validation](https://dry-rb.org/gems/dry-validation/) ~> 1.10 — ActionFigure uses dry-validation for schema validation. However, there's no dependency injection container, monads, or functional pipeline. Just a focused layer for controller actions.
 - Rails is not required, but ActionFigure is designed for Rails controller patterns
 
 ## License