action_figure 0.6.2 → 0.7.0

data/lib/action_figure/formatters/rfc_9457.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module ActionFigure
+  module Formatters
+    # Implements RFC 9457 (Problem Details for HTTP APIs) response helpers.
+    # Errors render as application/problem+json documents. Success responses
+    # mirror the same type/title vocabulary.
+    #
+    # Defaults for type and title are derived mechanically from class names and
+    # status symbols — deliberately unattractive. Pass type: and title: kwargs
+    # to provide stable, documented values your clients can rely on.
+    module Rfc9457
+      include ActionFigure::Formatter
+
+      def Ok(resource:, meta: nil, as: nil, type: nil, title: nil)
+        build_success(resource: resource, meta: meta, as: as,
+                      type: type, title: title, status: :ok)
+      end
+
+      def Created(resource:, meta: nil, as: nil, type: nil, title: nil)
+        build_success(resource: resource, meta: meta, as: as,
+                      type: type, title: title, status: :created)
+      end
+
+      def Accepted(resource: nil, meta: nil, as: nil, type: nil, title: nil)
+        build_success(resource: resource, meta: meta, as: as,
+                      type: type, title: title, status: :accepted)
+      end
+
+      def UnprocessableContent(errors: nil, type: "unprocessable-content-error", **extras)
+        error_response(status: :unprocessable_content, errors: errors, type: type, **extras)
+      end
+
+      # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
+      def error_response(status:, errors: nil, type: nil, title: nil, detail: nil, instance: nil, **extras)
+        name  = action_name_for_error
+        word  = status_word(status)
+        body  = {}
+        body[:type]     = type  || derive_type(name, "#{word}-error")
+        body[:title]    = title || rack_status_title(status)
+        body[:status]   = ActionFigure.status_code_for(status)
+        body[:detail]   = detail   if detail
+        body[:instance] = instance if instance
+        body[:errors]   = errors   unless errors.nil?
+        extras.each { |k, v| body[k] = v }
+        { json: body, status: status, content_type: "application/problem+json" }
+      end
+      # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
+
+      PRIMITIVE_CLASSES = [Hash, Array, String, Numeric, Symbol,
+                           TrueClass, FalseClass, NilClass].freeze
+
+      private
+
+      # rubocop:disable Metrics/ParameterLists
+      def build_success(resource:, meta:, as:, type:, title:, status:)
+        name, key = resource_info(resource, as)
+        word   = status_word(status)
+        body   = {}
+        body[:type]  = type  || derive_type(name, word)
+        body[:title] = title || derive_title(name, word)
+        body[key]    = resource unless resource.nil? && status == :accepted
+        body[:meta]  = meta if meta
+        { json: body, status: status }
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Returns [name, key] where name drives type/title derivation and key
+      # is the JSON member. Primitives and anonymous classes use name "resource"
+      # and key :data; model-like objects use their dasherized class name for both.
+      def resource_info(resource, as_kwarg)
+        if as_kwarg
+          name = dasherize_class_name(as_kwarg.to_s)
+          return [name, as_kwarg.to_sym]
+        end
+
+        klass = resource.class
+        return ["resource", :data] if primitive_class?(klass) || klass.name.nil?
+
+        name = dasherize_class_name(klass.name)
+        [name, name.gsub("-", "_").to_sym]
+      end
+
+      # Returns the action class's dasherized name (Action suffix stripped)
+      # for use as the error type prefix.
+      def action_name_for_error
+        klass_name = self.class.name
+        return "action" if klass_name.nil?
+
+        dasherize_class_name(klass_name)
+      end
+
+      # Converts a Ruby class name string (or an as: symbol) to a dasherized,
+      # Action-stripped slug.
+      # Examples:
+      #   "User"                 -> "user"
+      #   "Admin::UserProfile"   -> "admin-user-profile"
+      #   "Projects::CreateAction" -> "projects-create"
+      #   "user_profile"         -> "user-profile"
+      def dasherize_class_name(name)
+        name
+          .sub(/Action\z/, "")   # strip trailing "Action"
+          .gsub("::", "-")       # namespace separator -> dash
+          .tr("_", "-")          # snake_case as: symbols -> dashes
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2') # e.g. XMLParser -> XML-Parser
+          .gsub(/([a-z\d])([A-Z])/, '\1-\2') # camelCase -> camel-Case
+          .downcase
+          .squeeze("-")          # collapse any double-dashes from empty namespace parts
+          .sub(/\A-/, "")        # remove leading dash if Action was the only segment
+          .sub(/-\z/, "")        # remove trailing dash
+      end
+
+      # Status word derived from the Rack status symbol (underscores -> dashes).
+      # Examples: :ok -> "ok", :not_found -> "not-found", :created -> "created"
+      def status_word(status_symbol)
+        status_symbol.to_s.tr("_", "-")
+      end
+
+      def derive_type(name, word)
+        "#{name}-#{word}"
+      end
+
+      # Builds a human title from a dasherized name and a status word.
+      # Examples: ("user", "created") -> "User created"
+      #           ("admin-user-profile", "created") -> "Admin user profile created"
+      def derive_title(name, word)
+        phrase = "#{name.gsub("-", " ")} #{word.tr("-", " ")}"
+        phrase[0].upcase + phrase[1..]
+      end
+
+      def rack_status_title(status_symbol)
+        code = ActionFigure.status_code_for(status_symbol)
+        Rack::Utils::HTTP_STATUS_CODES[code] || status_symbol.to_s.tr("_", " ").capitalize
+      end
+
+      def primitive_class?(klass)
+        PRIMITIVE_CLASSES.any? { |p| klass <= p }
+      end
+    end
+  end
+end

data/lib/action_figure/formatters/wrapped.rb

@@ -25,24 +25,8 @@ module ActionFigure
         { 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
   end

data/lib/action_figure/testing/minitest.rb

@@ -1,58 +1,111 @@
 # frozen_string_literal: true
 
+require_relative "statuses"
+
 module ActionFigure
   module Testing
     # Minitest assertions for ActionFigure response results.
     #
-    # Include in your test class to get assert_Ok, assert_Created, etc.:
+    # Include in your test class to get assert_Ok, assert_Created, etc.
+    # (and the negated refute_Ok, refute_Created, ...):
     #
     #   class Users::CreateTest < Minitest::Test
     #     include ActionFigure::Testing::Minitest
     #   end
+    #
+    # The status helpers are generated from ActionFigure::Testing.statuses so the
+    # Minitest and RSpec adapters never drift.
     module Minitest
-      def assert_Ok(result, msg = nil)
-        assert_status(:ok, result, msg)
-      end
+      def self.define_status_assertions(name, status)
+        define_method(:"assert_#{name}") do |result, msg = nil|
+          assert_status(status, result, msg)
+        end
 
-      def assert_Created(result, msg = nil)
-        assert_status(:created, result, msg)
+        define_method(:"refute_#{name}") do |result, msg = nil|
+          refute_status(status, result, msg)
+        end
       end
 
-      def assert_Accepted(result, msg = nil)
-        assert_status(:accepted, result, msg)
-      end
+      Testing.statuses.each { |name, status| define_status_assertions(name, status) }
 
-      def assert_NoContent(result, msg = nil)
-        assert_status(:no_content, result, msg)
+      def assert_valid_params(action_class, params, msg = nil)
+        result = action_contract(action_class).call(params)
+        message = msg || "Expected params to be valid, but got errors: #{result.errors.to_h.inspect}"
+        assert result.success?, message
       end
 
-      def assert_UnprocessableContent(result, msg = nil)
-        assert_status(:unprocessable_content, result, msg)
+      def assert_invalid_params(action_class, params, on: nil, msg: nil)
+        result = action_contract(action_class).call(params)
+
+        if on.nil?
+          message = msg || "Expected params to be invalid, but the contract accepted them"
+          assert result.failure?, message
+        else
+          errored = result.errors.to_h.key?(on)
+          message = msg || "Expected params to be invalid on #{on.inspect}, " \
+                           "but errors were: #{result.errors.to_h.inspect}"
+          assert errored, message
+        end
       end
 
-      def assert_NotFound(result, msg = nil)
-        assert_status(:not_found, result, msg)
+      # Asserts +result[:json]+ contains the given fragment as a (possibly nested) subset.
+      # Mirrors the RSpec +have_action_json+ matcher: nested Hashes match as subsets and
+      # Regexp values match against strings.
+      #
+      #   assert_action_json(result, status: "success", data: { name: "Jane" })
+      def assert_action_json(result, fragment, msg = nil)
+        flunk(msg || "Expected an ActionFigure result hash, got #{result.inspect}") unless result.is_a?(Hash)
+        unless result.key?(:json)
+          flunk(msg || "Expected #{result.inspect} to include key :json (ActionFigure render hash)")
+        end
+
+        message = msg || "Expected result[:json] to include #{fragment.inspect}, got #{result[:json].inspect}"
+        assert json_subset?(result[:json], fragment), message
       end
 
-      def assert_Forbidden(result, msg = nil)
-        assert_status(:forbidden, result, msg)
+      def refute_action_json(result, fragment, msg = nil)
+        json = result.is_a?(Hash) ? result[:json] : nil
+        message = msg || "Expected result[:json] not to include #{fragment.inspect}"
+        refute(json.is_a?(Hash) && json_subset?(json, fragment), message)
       end
 
-      def assert_Conflict(result, msg = nil)
-        assert_status(:conflict, result, msg)
+      private
+
+      def json_subset?(actual, expected)
+        return false unless actual.is_a?(Hash)
+
+        expected.all? do |key, value|
+          actual.key?(key) && json_value_match?(actual[key], value)
+        end
       end
 
-      def assert_PaymentRequired(result, msg = nil)
-        assert_status(:payment_required, result, msg)
+      def json_value_match?(actual, expected)
+        case expected
+        when Hash then json_subset?(actual, expected)
+        when Regexp then expected.match?(actual.to_s)
+        else actual == expected
+        end
       end
 
-      private
+      def action_contract(action_class)
+        ActionFigure::Testing.contract_for(action_class)
+      end
 
       def assert_status(expected, result, msg)
+        flunk(msg || "Expected an ActionFigure result hash, got #{result.inspect}") unless result.is_a?(Hash)
+
         actual = result[:status]
         message = msg || "Expected result status to be #{expected.inspect}, but got #{actual.inspect}"
         assert actual == expected, message
       end
+
+      def refute_status(expected, result, msg)
+        flunk(msg || "Expected an ActionFigure result hash, got #{result.inspect}") unless result.is_a?(Hash)
+
+        actual = result[:status]
+        message = msg || "Expected result status not to be #{expected.inspect}"
+        refute actual == expected, message
+      end
     end
   end
 end

data/lib/action_figure/testing/rspec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rspec/matchers"
+require_relative "statuses"
 
 module ActionFigure
   module Testing
@@ -17,22 +18,12 @@ module ActionFigure
     #     end
     #   end
     module RSpec
-      MATCHERS = {
-        Ok: :ok,
-        Created: :created,
-        Accepted: :accepted,
-        NoContent: :no_content,
-        UnprocessableContent: :unprocessable_content,
-        NotFound: :not_found,
-        Forbidden: :forbidden,
-        Conflict: :conflict,
-        PaymentRequired: :payment_required
-      }.freeze
-
-      MATCHERS.each do |name, status|
+      def self.define_status_matcher(name, status)
         ::RSpec::Matchers.define :"be_#{name}" do
-          match { |result| result[:status] == status }
+          match { |result| result.is_a?(Hash) && result[:status] == status }
           failure_message do |result|
+            next "expected an ActionFigure result hash, got #{result.inspect}" unless result.is_a?(Hash)
+
             "expected result status to be #{status.inspect}, but got #{result[:status].inspect}"
           end
           failure_message_when_negated do
@@ -41,6 +32,8 @@ module ActionFigure
         end
       end
 
+      Testing.statuses.each { |name, status| define_status_matcher(name, status) }
+
       # Asserts against +result[:json]+ using +a_hash_including+ (nested matchers allowed).
       ::RSpec::Matchers.define :have_action_json do |expected_fragment|
         include ::RSpec::Matchers
@@ -67,6 +60,52 @@ module ActionFigure
           "#{result.inspect} was expected not to match #{@inner_matcher.description}"
         end
       end
+
+      # Asserts an action class's params_schema/rules accept the given params.
+      # Subject is the action class, not a result hash:
+      #
+      #   expect(Users::Create).to accept_params(email: "jane@example.com")
+      ::RSpec::Matchers.define :accept_params do |params|
+        match { |action_class| ActionFigure::Testing.contract_for(action_class).call(params).success? }
+
+        failure_message do |action_class|
+          errors = ActionFigure::Testing.contract_for(action_class).call(params).errors.to_h
+          "expected #{action_class} to accept params, but got errors: #{errors.inspect}"
+        end
+
+        failure_message_when_negated do |action_class|
+          "expected #{action_class} not to accept params #{params.inspect}, but it did"
+        end
+      end
+
+      # Asserts an action class's params_schema/rules reject the given params.
+      # Chain +with_error_on+ to require the failure to land on a specific field:
+      #
+      #   expect(Users::Create).to reject_params(name: "Jane").with_error_on(:email)
+      ::RSpec::Matchers.define :reject_params do |params|
+        chain(:with_error_on) { |field| @field = field }
+
+        match do |action_class|
+          errors = ActionFigure::Testing.contract_for(action_class).call(params).errors.to_h
+          next false if errors.empty?
+
+          @field.nil? || errors.key?(@field)
+        end
+
+        failure_message do |action_class|
+          errors = ActionFigure::Testing.contract_for(action_class).call(params).errors.to_h
+          if @field
+            "expected #{action_class} to reject params with an error on #{@field.inspect}, " \
+              "but errors were: #{errors.inspect}"
+          else
+            "expected #{action_class} to reject params #{params.inspect}, but it accepted them"
+          end
+        end
+
+        failure_message_when_negated do |action_class|
+          "expected #{action_class} not to reject params #{params.inspect}"
+        end
+      end
     end
   end
 end

data/lib/action_figure/testing/statuses.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "action_figure"
+
+module ActionFigure
+  # Helpers shared by the Minitest and RSpec testing adapters.
+  module Testing
+    # Success/no-body statuses with bespoke formatter bodies. These are not part of
+    # the error registry (their bodies differ per outcome, not just per status).
+    SUCCESS_STATUSES = {
+      Ok: :ok,
+      Created: :created,
+      Accepted: :accepted,
+      NoContent: :no_content
+    }.freeze
+
+    # Live full name→status map driving both adapters: success statuses plus
+    # every error status registered so far (built-in and user-registered).
+    # Each adapter iterates this at its own load time, so an adapter loaded
+    # after a +register_error+ call still sees the full registry; registrations
+    # made after an adapter loads are patched in via +define_error_helper+.
+    def self.statuses
+      SUCCESS_STATUSES.merge(ActionFigure.error_statuses)
+    end
+
+    # Resolves an action class's validation contract, raising a clear error when
+    # the class declares no +params_schema+ (and therefore has no contract).
+    def self.contract_for(action_class)
+      contract = action_class.contract
+      return contract if contract
+
+      raise ArgumentError,
+            "#{action_class} defines no params_schema, so it has no contract to validate against"
+    end
+
+    # Patches whichever adapters are loaded with one status's assertion/matcher.
+    # Called by ActionFigure.register_error so a status registered after the
+    # adapters have loaded still gets its assert_/refute_/be_ helpers.
+    # +const_defined?(..., false)+ checks only this namespace — a bare
+    # +defined?(Minitest)+ would find the top-level framework constant.
+    def self.define_error_helper(name, status)
+      Minitest.define_status_assertions(name, status) if const_defined?(:Minitest, false)
+      RSpec.define_status_matcher(name, status) if const_defined?(:RSpec, false)
+    end
+  end
+end

data/lib/action_figure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionFigure
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end

data/lib/action_figure.rb

@@ -3,25 +3,25 @@
 require_relative "action_figure/version"
 require_relative "action_figure/configuration"
 require_relative "action_figure/format_registry"
+require_relative "action_figure/error_registry"
 require_relative "action_figure/formatter"
 require_relative "action_figure/core"
 require_relative "action_figure/formatters/jsend"
 require_relative "action_figure/formatters/json_api"
 require_relative "action_figure/formatters/default"
 require_relative "action_figure/formatters/wrapped"
+require_relative "action_figure/formatters/rfc_9457"
 
 # ActionFigure provides explicit, purpose-driven operation classes for Rails controller actions.
 module ActionFigure
+  @format_modules = Concurrent::Map.new
+
   extend Configuration
   extend FormatRegistry
+  extend ErrorRegistry
 
   class IndeterminateEntryPointError < StandardError; end
 
-  # Backwards-compatible alias for the misspelled constant shipped through 0.6.0.
-  # Remove in the next minor release after Unreleased.
-  IndeterminantEntryPointError = IndeterminateEntryPointError
-  deprecate_constant :IndeterminantEntryPointError
-
   # Raised when an action class defines +initialize+. ActionFigure builds instances with
   # +new+ and passes no constructor arguments; use keyword arguments on the entry method
   # or class-level state instead of custom initializers.
@@ -31,6 +31,7 @@ module ActionFigure
   register_formatter(jsonapi: Formatters::JsonApi)
   register_formatter(default: Formatters::Default)
   register_formatter(wrapped: Formatters::Wrapped)
+  register_formatter(rfc_9457: Formatters::Rfc9457) # rubocop:disable Naming/VariableNumber
 
   def self.[](format = configuration.format)
     format_modules.compute_if_absent(format) { build_format_module(format, fetch(format)) }
@@ -78,7 +79,7 @@ module ActionFigure
   private_class_method :new_format_module
 
   def self.format_modules
-    @format_modules ||= Concurrent::Map.new
+    @format_modules
   end
   private_class_method :format_modules
 end

data/sig/action_figure.rbs

@@ -12,19 +12,20 @@ module ActionFigure
   class IndeterminateEntryPointError < StandardError
   end
 
-  # Deprecated alias for IndeterminateEntryPointError (misspelled constant from <= 0.6.0).
-  IndeterminantEntryPointError: Class
-
   class InitializationNotSupportedError < StandardError
   end
 
   extend Configuration
   extend FormatRegistry
+  extend ErrorRegistry
 
   def self.[]: (?Symbol format) -> Module
   def self.included: (Module base) -> void
   def self.register_formatter: (**Module formatters) -> void
   def self.clear_format_module_cache: (Symbol name) -> void
+  def self.error_statuses: () -> Hash[Symbol, Symbol]
+  def self.register_error: (Symbol | String name, Symbol | String status_symbol) -> Symbol
+  def self.status_code_for: (Symbol status_symbol) -> Integer
 
   # Provides global configuration via ActionFigure.configure
   module Configuration
@@ -55,8 +56,36 @@ module ActionFigure
     def fetch: (Symbol name) -> Module
   end
 
+  # Central registry of error-helper name → status symbol mappings.
+  module ErrorRegistry
+    DEFAULTS: Hash[Symbol, Symbol]
+    STATUS_CODE_FALLBACKS: Hash[Symbol, Integer]
+
+    # Live module carrying one generated error helper per registered status.
+    # Helpers for user-registered statuses are defined at runtime; the
+    # built-in ones are declared explicitly so the signatures stay visible.
+    module Helpers
+      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Gone: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def Locked: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def UnavailableForLegalReasons: (errors: ActionFigure::error_hash) -> ActionFigure::response
+    end
+
+    def self.define_helper: (Symbol name, Symbol status_symbol) -> void
+
+    def error_statuses: () -> Hash[Symbol, Symbol]
+    def register_error: (Symbol | String name, Symbol | String status_symbol) -> Symbol
+    def status_code_for: (Symbol status_symbol) -> Integer
+  end
+
   # Base module for response formatters
   module Formatter
+    include ErrorRegistry::Helpers
+
     REQUIRED_METHODS: Array[Symbol]
 
     def NoContent: () -> ActionFigure::response
@@ -102,11 +131,7 @@ module ActionFigure
       def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
-      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def error_response: (errors: ActionFigure::error_hash, status: Symbol) -> ActionFigure::response
     end
 
     # JSend-formatted responses
@@ -116,11 +141,7 @@ module ActionFigure
       def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
-      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def error_response: (errors: ActionFigure::error_hash, status: Symbol) -> ActionFigure::response
     end
 
     # JSON:API-formatted responses
@@ -130,11 +151,7 @@ module ActionFigure
       def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
-      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def error_response: (errors: ActionFigure::error_hash, status: Symbol) -> ActionFigure::response
 
       # Simple resource serialization for JSON:API
       class Resource
@@ -149,17 +166,31 @@ module ActionFigure
       def Ok: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Created: (resource: untyped, ?meta: untyped?) -> ActionFigure::response
       def Accepted: (?resource: untyped?, ?meta: untyped?) -> ActionFigure::response
-      def UnprocessableContent: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def NotFound: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Forbidden: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def Conflict: (errors: ActionFigure::error_hash) -> ActionFigure::response
-      def PaymentRequired: (errors: ActionFigure::error_hash) -> ActionFigure::response
+      def error_response: (errors: ActionFigure::error_hash, status: Symbol) -> ActionFigure::response
     end
   end
 
   module Testing
-    # Minitest assertions for action response results
+    # Success-only statuses (Ok, Created, Accepted, NoContent).
+    SUCCESS_STATUSES: Hash[Symbol, Symbol]
+
+    # Live map of status-helper names to status symbols: success statuses plus
+    # every registered error status.
+    def self.statuses: () -> Hash[Symbol, Symbol]
+
+    # Resolves an action class's validation contract (RSpec adapter helper).
+    def self.contract_for: (untyped action_class) -> untyped
+
+    # Defines assert_/refute_ and be_ helpers for a dynamically registered status.
+    def self.define_error_helper: (Symbol name, Symbol status) -> void
+
+    # Minitest assertions for action response results.
+    #
+    # assert_* / refute_* status helpers are generated from Testing.statuses at
+    # load time; they are declared explicitly here so the signatures stay visible.
     module Minitest
+      def self.define_status_assertions: (Symbol name, Symbol status) -> void
+
       def assert_Ok: (ActionFigure::response result, ?String? msg) -> void
       def assert_Created: (ActionFigure::response result, ?String? msg) -> void
       def assert_Accepted: (ActionFigure::response result, ?String? msg) -> void
@@ -169,11 +200,35 @@ module ActionFigure
       def assert_Forbidden: (ActionFigure::response result, ?String? msg) -> void
       def assert_Conflict: (ActionFigure::response result, ?String? msg) -> void
       def assert_PaymentRequired: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Gone: (ActionFigure::response result, ?String? msg) -> void
+      def assert_Locked: (ActionFigure::response result, ?String? msg) -> void
+      def assert_UnavailableForLegalReasons: (ActionFigure::response result, ?String? msg) -> void
+
+      def refute_Ok: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Created: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Accepted: (ActionFigure::response result, ?String? msg) -> void
+      def refute_NoContent: (ActionFigure::response result, ?String? msg) -> void
+      def refute_UnprocessableContent: (ActionFigure::response result, ?String? msg) -> void
+      def refute_NotFound: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Forbidden: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Conflict: (ActionFigure::response result, ?String? msg) -> void
+      def refute_PaymentRequired: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Gone: (ActionFigure::response result, ?String? msg) -> void
+      def refute_Locked: (ActionFigure::response result, ?String? msg) -> void
+      def refute_UnavailableForLegalReasons: (ActionFigure::response result, ?String? msg) -> void
+
+      def assert_valid_params: (untyped action_class, untyped params, ?String? msg) -> void
+      def assert_invalid_params: (untyped action_class, untyped params, ?on: Symbol?, ?msg: String?) -> void
+
+      def assert_action_json: (ActionFigure::response result, Hash[Symbol, untyped] fragment, ?String? msg) -> void
+      def refute_action_json: (ActionFigure::response result, Hash[Symbol, untyped] fragment, ?String? msg) -> void
     end
 
-    # RSpec custom matchers (be_Ok, be_Created, etc.)
+    # RSpec custom matchers: status matchers (be_Ok, ...), have_action_json,
+    # and the contract matchers accept_params / reject_params are registered
+    # globally via RSpec::Matchers.define and so are not module methods.
     module RSpec
-      MATCHERS: Hash[Symbol, Symbol]
+      def self.define_status_matcher: (Symbol name, Symbol status) -> void
     end
   end
 end