action_figure 0.5.0 → 0.6.2

data/docs/actions.md

@@ -6,9 +6,9 @@ An ActionFigure action class is a single-purpose operation. Each class encapsula
 
 ---
 
-## The Default: `call`
+## Naming Your Action Method
 
-Every action class gets a `.call` class method when it includes ActionFigure. It instantiates the class, runs the validation pipeline (if `params:` is provided), and delegates to the instance-level `#call` method.
+ActionFigure auto-discovers your action method by name. Define one public instance method on your action class and ActionFigure registers it as the entry point -- no macro required:
 
 ```ruby
 class Users::CreateAction
@@ -21,7 +21,7 @@ class Users::CreateAction
     end
   end
 
-  def call(params:, company:, **)
+  def create(params:, company:, **)
     user = company.users.create(params[:user])
     return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
 
@@ -30,21 +30,47 @@ class Users::CreateAction
 end
 ```
 
-Wire it into a controller by passing `params:` and any additional context:
+Wire it into a controller using the discovered method name:
 
 ```ruby
 class UsersController < ApplicationController
   def create
-    render Users::CreateAction.call(params:, company: current_company)
+    render Users::CreateAction.create(params:, company: current_company)
   end
 end
 ```
 
----
+### How it works
+
+ActionFigure uses a `method_added` hook to watch for public instance methods defined on the class. The first public method defined becomes the registered entry point and a matching class-level method is created for it. The full validation pipeline (`params_schema` and `rules`) still runs through the discovered entry point before your method is invoked.
+
+Do not define **`initialize`** on action classes: ActionFigure calls **`new`** with no arguments each time work runs. A custom initializer raises **`InitializationNotSupportedError`** (even if `initialize` is private or you used **`entry_point`**). Prefer keyword arguments on the entry method or class-level collaborators for dependencies instead.
+
+Overview of discovery (**`entry_point`** sidesteps ambiguity by wiring the singleton up front):
+
+```mermaid
+flowchart TD
+  A[include mixes Core + formatter] --> B["method_added fires for each new method"]
+  B --> C{"`entry_point` macro already declared?"}
+  C -->|"yes"| D[Skip auto-discovery;\nsingleton was defined by the macro]
+  C -->|"no"| E{"Public instance method owned by\nthis action class?"}
+  E -->|"no"| B
+  E -->|"yes"| F{"First discovered entry?"}
+  F -->|"yes"| G["Remember name;\ndefine .name(**kwargs) -> validated_call"]
+  F -->|"no"| H["Raise IndeterminateEntryPointError"]
+```
 
-## Custom Entry Points
+### Disambiguation with `entry_point`
 
-Some actions have a name that reads better than `.call`. The `entry_point` macro declares an alternative class-level method name:
+If a class ends up with more than one public instance method, ActionFigure cannot determine which one to use and raises an `IndeterminateEntryPointError`:
+
+```
+ActionFigure::IndeterminateEntryPointError: Multiple public methods defined in Orders::SearchAction:
+:search and :format_results. Either make one private or declare
+`entry_point :search` to disambiguate.
+```
+
+Use the `entry_point` macro to resolve this:
 
 ```ruby
 class Orders::SearchAction
@@ -66,46 +92,34 @@ class Orders::SearchAction
     resource = orders.as_json(only: %i[id tracking_number status])
     Ok(resource:)
   end
-end
-```
 
-Call it from a controller using the declared name:
+  private
 
-```ruby
-class OrdersController < ApplicationController
-  def index
-    render Orders::SearchAction.search(params:, company: current_company)
+  def build_scope(company)
+    company.orders.active
   end
 end
 ```
 
-### How it works
-
-- The instance method must match the declared entry point name (`:search` declares `.search` and expects `#search`). If an entry point is defined, any instance-level `#call` method is ignored by the class-level entry point.
-- The full validation pipeline still runs through the custom entry point -- `params_schema` and `rules` are applied before your method is invoked.
-- Calling `.call` on a class that declares a custom entry point raises a `NoMethodError` with a helpful message:
+Only one entry point per class is allowed. A second `entry_point` declaration raises an `ArgumentError`:
 
-  ```
-  NoMethodError: undefined method 'call' for Orders::SearchAction (use 'search' instead)
-  ```
-
-- Only one entry point per class is allowed. A second `entry_point` declaration raises an `ArgumentError`:
-
-  ```
-  ArgumentError: entry_point already defined as 'search' — each action class may declare only one entry point
-  ```
+```
+ArgumentError: entry_point already defined as 'search' — each action class may declare only one entry point
+```
 
 ---
 
-## No-Params Actions
+## Actions Without a Schema
+
+Actions that omit `params_schema` skip the validation pipeline entirely. Any `params:` passed through are delivered to your method as-is — no coercion, no stripping, no validation.
 
-Actions that don't need validated input simply omit `params_schema`. The validation pipeline is skipped entirely.
+This is useful when validation is handled upstream (e.g., Rack middleware like `committee` validating against an OpenAPI spec) or when the action simply doesn't need params:
 
 ```ruby
 class HealthCheckAction
   include ActionFigure[:jsend]
 
-  def call
+  def check
     Ok(resource: { status: "healthy", time: Time.current })
   end
 end
@@ -114,17 +128,11 @@ end
 ```ruby
 class HealthController < ApplicationController
   def show
-    render HealthCheckAction.call
+    render HealthCheckAction.check
   end
 end
 ```
 
-If you accidentally pass `params:` to an action that has no schema, ActionFigure raises immediately:
-
-```
-ArgumentError: params: passed but no params_schema defined
-```
-
 ---
 
 ## Context Injection
@@ -142,7 +150,7 @@ class Users::CreateAction
     end
   end
 
-  def call(params:, company:, current_user:)
+  def create(params:, company:, current_user:)
     user = company.users.create(params[:user].merge(invited_by: current_user))
     return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
 
@@ -154,7 +162,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def create
-    render Users::CreateAction.call(
+    render Users::CreateAction.create(
       params:,
       company: current_company,
       current_user: current_user
@@ -175,7 +183,7 @@ A simple index action needs no params and no schema:
 class Users::IndexAction
   include ActionFigure[:jsend]
 
-  def call(company:)
+  def index(company:)
     users = company.users.order(:name)
     Ok(resource: users.as_json(only: %i[id name email]))
   end
@@ -185,7 +193,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def index
-    render Users::IndexAction.call(company: current_company)
+    render Users::IndexAction.index(company: current_company)
   end
 end
 ```
@@ -200,7 +208,7 @@ class Users::ShowAction
     required(:id).filled(:integer)
   end
 
-  def call(params:, company:)
+  def show(params:, company:)
     user = company.users.find_by(id: params[:id])
     return NotFound(errors: { base: ["user not found"] }) unless user
 
@@ -212,7 +220,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def show
-    render Users::ShowAction.call(params:, company: current_company)
+    render Users::ShowAction.show(params:, company: current_company)
   end
 end
 ```
@@ -230,7 +238,7 @@ class Users::CreateAction
     end
   end
 
-  def call(params:, company:)
+  def create(params:, company:)
     user = company.users.create(params[:user])
     return UnprocessableContent(errors: user.errors.messages) unless user.persisted?
 
@@ -242,7 +250,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def create
-    render Users::CreateAction.call(params:, company: current_company)
+    render Users::CreateAction.create(params:, company: current_company)
   end
 end
 ```
@@ -261,7 +269,7 @@ class Users::UpdateAction
     end
   end
 
-  def call(params:, company:)
+  def update(params:, company:)
     user = company.users.find_by(id: params[:id])
     return NotFound(errors: { base: ["user not found"] }) unless user
 
@@ -276,7 +284,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def update
-    render Users::UpdateAction.call(params:, company: current_company)
+    render Users::UpdateAction.update(params:, company: current_company)
   end
 end
 ```
@@ -291,7 +299,7 @@ class Users::DestroyAction
     required(:id).filled(:integer)
   end
 
-  def call(params:, company:)
+  def destroy(params:, company:)
     user = company.users.find_by(id: params[:id])
     return NotFound(errors: { base: ["user not found"] }) unless user
 
@@ -304,7 +312,7 @@ end
 ```ruby
 class UsersController < ApplicationController
   def destroy
-    render Users::DestroyAction.call(params:, company: current_company)
+    render Users::DestroyAction.destroy(params:, company: current_company)
   end
 end
 ```
@@ -325,7 +333,7 @@ class Users::BulkInviteAction
     required(:emails).value(:array, min_size?: 1).each(:str?)
   end
 
-  def call(params:, company:)
+  def invite(params:, company:)
     result = BulkInviteService.call(emails: params[:emails], company: company)
     return UnprocessableContent(errors: result.errors) if result.failures?
 
@@ -337,7 +345,7 @@ end
 ```ruby
 class Users::InvitesController < ApplicationController
   def create
-    render Users::BulkInviteAction.call(params:, company: current_company)
+    render Users::BulkInviteAction.invite(params:, company: current_company)
   end
 end
 ```
@@ -356,7 +364,7 @@ class Reports::GenerateAction
     end
   end
 
-  def call(params:, current_user:)
+  def generate(params:, current_user:)
     result = ReportService.enqueue(params: params[:report], requested_by: current_user)
     return UnprocessableContent(errors: result.errors) if result.failed?
 
@@ -368,7 +376,7 @@ end
 ```ruby
 class ReportsController < ApplicationController
   def create
-    render Reports::GenerateAction.call(params:, current_user: current_user)
+    render Reports::GenerateAction.generate(params:, current_user: current_user)
   end
 end
 ```
@@ -379,7 +387,7 @@ File imports work the same way — receive the file, hand it off, translate the
 class Products::ImportAction
   include ActionFigure[:jsend]
 
-  def call(file:, company:)
+  def import(file:, company:)
     result = ProductImportService.call(file: file, company: company)
     return UnprocessableContent(errors: result.errors) if result.failed?
 
@@ -391,7 +399,7 @@ end
 ```ruby
 class Products::ImportsController < ApplicationController
   def create
-    render Products::ImportAction.call(file: params[:file], company: current_company)
+    render Products::ImportAction.import(file: params[:file], company: current_company)
   end
 end
 ```
@@ -415,7 +423,7 @@ class Users::CreateAction
     end
   end
 
-  def call(params:)
+  def create(params:)
     user = User.create(params[:user])
     return UnprocessableContent(errors: user.errors.messages) if user.errors.any?
 
@@ -435,7 +443,7 @@ Users::CreateAction.api_version  #=> "2.0"
 Inside an action instance, access it through the class:
 
 ```ruby
-def call(params:, **)
+def create(params:, **)
   if self.class.api_version == "2.0"
     # v2 behavior
   end
@@ -452,7 +460,7 @@ ActionFigure.configure do |config|
 end
 ```
 
-The global version is accessible via `ActionFigure.configuration.api_version` but is not used as an automatic fallback for class-level `api_version`. Version values are independent per class -- they are not inherited by subclasses because version state is stored in class-level instance variables.
+The global value reads from **`ActionFigure.configuration.api_version`**. It never acts as an automatic fallback for **`api_version` on the class**: the two strings are intentionally separate. Use **`config.api_version`** for **infra-wide defaults** — release dashboards, outbound headers assembled in middleware, initializer documentation — without forcing each action constant to duplicate the same value. Put **`api_version "2.0"`** on classes when that action participates in explicit version branching. Versions are independent per class and **not inherited** by subclasses (state lives in class-level instance variables).
 
 ---
 

data/docs/activesupport-notifications.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-ActionFigure can provide notifications in action execution via `ActiveSupport::Notifications`. When enabled, every `.call` (or custom entry point) emits a `process.action_figure` event with the action class name, outcome status, and timing.
+ActionFigure can provide notifications in action execution via `ActiveSupport::Notifications`. When enabled, every class-level trigger (`:call`, `:create`, `:search`, etc.) emits a `process.action_figure` event with the action class name, entry-point symbol, outcome status, and timing.
 
 Notifications are **off by default** and requires both ActiveSupport and an explicit opt-in.
 
@@ -30,10 +30,11 @@ process.action_figure
 
 ## Payload
 
-| Key      | Type   | Description |
-|----------|--------|-------------|
-| `action` | String | The action class name, e.g. `"Users::CreateAction"` |
-| `status` | Symbol | The outcome status, e.g. `:ok`, `:created` |
+| Key           | Type   | Description |
+|---------------|--------|-------------|
+| `action`      | String | The action class name, e.g. `"Users::CreateAction"` |
+| `entry_point` | Symbol | The dispatched instance method (`:call`, `:create`, `:search`, etc.). Always set when the event is emitted — events are only instrumented from the singleton method created during entry-point discovery, so `nil` is not observable in subscribers even though `ClassMethods#entry_point_name` is nullable internally (pre-discovery). |
+| `status`      | Symbol | The outcome status (set after completion), e.g. `:ok`, `:created` |
 
 Timing (duration, start, end) is provided automatically by `ActiveSupport::Notifications`.
 
@@ -44,7 +45,7 @@ Timing (duration, start, end) is provided automatically by `ActiveSupport::Notif
 ```ruby
 ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
   Rails.logger.info(
-    "#{event.payload[:action]} => #{event.payload[:status]} (#{event.duration.round(1)}ms)"
+    "#{event.payload[:action]}##{event.payload[:entry_point]} => #{event.payload[:status]} (#{event.duration.round(1)}ms)"
   )
 end
 ```
@@ -52,16 +53,16 @@ end
 Output:
 
 ```
-Users::CreateAction => :created (12.3ms)
-Orders::SearchAction => :ok (45.7ms)
-Users::CreateAction => :unprocessable_content (1.1ms)
+Users::CreateAction#call => :created (12.3ms)
+Orders::SearchAction#search => :ok (45.7ms)
+Users::CreateAction#call => :unprocessable_content (1.1ms)
 ```
 
 ---
 
 ## What Gets Instrumented
 
-The event wraps the entire action lifecycle -- validation, the `#call` method, and the formatted response. Both successful and failed outcomes are captured:
+The event wraps the entire action lifecycle — validation, the entry-point instance method, and the formatted response. Both successful and failed outcomes are captured:
 
 - Validation failures (e.g. missing required params) produce events with status `:unprocessable_content`
 - Successful calls produce events with whatever status the action returns (`:ok`, `:created`, etc.)
@@ -90,6 +91,7 @@ ActiveSupport::Notifications.subscribe("process.action_figure") do |event|
     event.duration,
     tags: {
       action: event.payload[:action],
+      entry_point: event.payload[:entry_point],
       status: event.payload[:status]
     }
   )

data/docs/configuration.md

@@ -15,15 +15,29 @@ end
 
 The block yields an `ActionFigure::Configuration::Settings` instance. Call any combination of setters inside.
 
+## When configuration applies (load order)
+
+**Default formatter.** With bare `include ActionFigure`, Ruby calls **`ActionFigure.[]`** (no argument) during that line — it mixes in whichever formatter **`ActionFigure.configuration.format`** selects **in that moment**. Later calls to **`ActionFigure.configure`** (changing **`format`**) do **not** swap formatters inside classes that already finished `include`. Run **`configure`** in an initializer (or equivalent) **before** your action classes load, or skip the ambiguity altogether with **`include ActionFigure[:jsonapi]`** (or another registered name).
+
+**Notifications.** **`activesupport_notifications`** is consulted when the mixin’s **`included`** hook runs for your action class. If you turn **`c.activesupport_notifications = true`** only after constants have already loaded their `include` line, existing classes stay without the notifier extension; newly loaded classes get it.
+
+**Per-class knobs** such as **`include ActionFigure[:wrapped]`**, **`entry_point :search`**, and **`api_version "2.0"`** remain whatever you wrote in each class regardless of subsequent global **`configure`** calls.
+
 ## Settings Reference
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `format` | Symbol | `:default` | Default formatter name. Applies to any class that uses bare `include ActionFigure`. |
+| `format` | Symbol | `:default` | Formatter for bare **`include ActionFigure`**. Locked in when that line runs — see **When configuration applies (load order)** above. |
 | `whiny_extra_params` | Boolean | `false` | When `true`, returns an error response for undeclared params instead of silently stripping them. |
-| `activesupport_notifications` | Boolean | `false` | When `true`, enables `ActiveSupport::Notifications` events for action classes defined after the change. Requires ActiveSupport. |
+| `activesupport_notifications` | Boolean | `false` | When `true` and ActiveSupport is defined, emits **`process.action_figure`** for classes whose mixin runs **after** the flag was set — see load order note above. |
 | `api_version` | String or nil | `nil` | Global API version tag, readable via `ActionFigure.configuration.api_version`. |
 
+## Thread safety and global state
+
+`ActionFigure.configure` assigns to a **process-wide singleton** (`ActionFigure.configuration`). For production, set globals **once during boot**. In **multi-threaded** code or parallel test workers, flipping settings concurrently can interfere across threads — snapshot and restore in `ensure` (as the gem’s tests do with `whiny_extra_params`) or avoid mutating globals after boot.
+
+---
+
 ## Registering Formatters via Config
 
 You can register custom formatters inside the configure block with `register`:

data/docs/custom-formatters.md

@@ -11,7 +11,7 @@ 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 6 required methods.
+- A contract enforced at registration time: your module **must** define all 8 required methods.
 
 The required methods are:
 
@@ -23,6 +23,8 @@ The required methods are:
 | `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         |
 
 `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.
 
@@ -48,8 +50,10 @@ module WrappedFormatter
     { json: body, status: :created }
   end
 
-  def Accepted(resource: nil)
-    { json: { data: resource, errors: nil, status: "success" }, status: :accepted }
+  def Accepted(resource: nil, meta: nil)
+    body = { data: resource, errors: nil, status: "success" }
+    body[:meta] = meta if meta
+    { json: body, status: :accepted }
   end
 
   def UnprocessableContent(errors:)
@@ -63,10 +67,18 @@ module WrappedFormatter
   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 }
+  end
 end
 ```
 
-All 6 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 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.
 
 ## Registering Your Formatter
 
@@ -103,7 +115,7 @@ Registration is not just bookkeeping -- ActionFigure validates every formatter m
 
 ```ruby
 ActionFigure::Formatter::REQUIRED_METHODS
-# => [:Ok, :Created, :Accepted, :UnprocessableContent, :NotFound, :Forbidden]
+# => [:Ok, :Created, :Accepted, :UnprocessableContent, :NotFound, :Forbidden, :Conflict, :PaymentRequired]
 ```
 
 If any required method is missing, registration raises an `ArgumentError` that lists exactly which methods are absent:
@@ -119,7 +131,7 @@ end
 
 ActionFigure.register_formatter(incomplete: IncompleteFormatter)
 # => ArgumentError: IncompleteFormatter is missing formatter methods: Created, Accepted,
-#    UnprocessableContent, NotFound, Forbidden
+#    UnprocessableContent, NotFound, Forbidden, Conflict, PaymentRequired
 ```
 
 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.