action_spec 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4483d08f3dbf8917159d539ee9b064366551409ae646714def0b89595484428
-  data.tar.gz: 065af0d1f835124179afef0a756515b6184598cd35ef217a96615f18b2098cbe
+  metadata.gz: 06b66175d9094e2a53ff6c65cdfd88ad24f91724535ff8e0152341e079d18d0b
+  data.tar.gz: 562f73d96c1f1d57a72ec04e866a14a14fbcf0e12df757ed3b9a334a977450cd
 SHA512:
-  metadata.gz: 71ae3fd218312cb0e788f7a5affad8e31da416546e319852509d260490fe261009be24fc51cedfc5948c8c7e9cee04285b50019e613316f3a96605d7cee98b1f
-  data.tar.gz: 7aaee031ed042a3631c952789ccf4ca37db7f7a7f53fcb6a45f1a0e8c4badad005cd4e8774fad58d467c8b2f49d543f4d499407b98cad4dde8fe4e6dbe7cc197
+  metadata.gz: 581a39acd1d534f2c81647d8f9877423bcb53e6ea2ef0deab20c071c88a9fd160351721591e8af4007f2d9543c8375089017247a2a48a1314cb76421d40f08c5
+  data.tar.gz: 8db69ee15a9ac6cf205e8ce40563456f498cb6a2b31ee87104ce1fe524fc33efe46caf11fb151d114380c599ecd3060eaa910185d1915ed6e42e9959186a8af6

data/README.md

@@ -10,8 +10,9 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
 
 ## Table Of Contents
 
-1. [OpenAPI Generation](#openapi-generation)
-2. [Doc DSL](#doc-dsl)
+1. [AI Agent Quick Reference](#ai-agent-quick-reference)
+2. [OpenAPI Generation](#openapi-generation)
+3. [Doc DSL](#doc-dsl)
    1. [`doc`](#doc)
    2. [`doc_dry`](#doc_dry)
    3. [DSL Inside `doc`](#dsl-inside-doc)
@@ -20,21 +21,21 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
       3. [`openapi false`](#openapi-false)
       4. [Scope](#scope)
       5. [Response](#response)
-3. [Schemas](#schemas)
+4. [Schemas](#schemas)
    1. [Declare A Required Field](#declare-a-required-field)
    2. [Field Types](#field-types)
    3. [Field Options](#field-options)
    4. [Schemas From ActiveRecord](#schemas-from-activerecord)
    5. [Type And Boundary Matrix](#type-and-boundary-matrix)
-4. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
+5. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
    1. [Validation Flow](#validation-flow)
    2. [Reading Processed Values With `px`](#reading-processed-values-with-px)
    3. [`px` is Whitelist Extraction](#px-is-whitelist-extraction)
    4. [Errors](#errors)
-5. [Configuration And I18n](#configuration-and-i18n)
+6. [Configuration And I18n](#configuration-and-i18n)
    1. [Configuration](#configuration)
    2. [I18n](#i18n)
-6. [AI Generation Style Guide](#ai-generation-style-guide)
+7. [AI Generation Style Guide](#ai-generation-style-guide)
 
 ## Example
 
@@ -71,6 +72,18 @@ class UsersController < ApplicationController
 end
 ```
 
+## AI Agent Quick Reference
+
+When generating Rails controller code with ActionSpec, use these as the canonical choices:
+
+- put `doc { }` or `doc("Summary") { }` immediately above the action method and let ActionSpec infer the action name
+- use `{ }` blocks inside `doc`
+- prefer bang required syntax, such as `query! :id, Integer` and `name!: String`; keep `required: true` for compatibility or generated schemas
+- fold simple nested hash fields, `data: { }`, or `in_xxx(...)` declarations into one line when they have 2 fields or fewer and no complex nesting, such as `json data: { name: String, age: Integer }` or `in_query(name: String, value: String)`
+- declare body fields as `json data: { name!: String }` or `form data: { avatar!: File }`
+- use `doc_dry`, `scope`, `transform`, `px` / `px_key`, `.schemas`, and `px.slice` to keep controller actions small
+- rely on ActionSpec for parameter validation, type coercion, defaults, and similar contracts instead of rewriting the same parameter handling by hand
+
 ## Installation
 
 ```ruby
@@ -142,7 +155,7 @@ def create
 end
 ```
 
-You can also bind it explicitly when you want the action name declared in place:
+Escape hatch: bind the action explicitly when the inferred next method is not the intended action:
 
 ```ruby
 doc(:create, "Create user") {
@@ -211,7 +224,7 @@ end
 
 With `required_allow_blank = false`, required fields reject blank strings unless that field explicitly sets `blank:` or `allow_blank:`.
 
-If you prefer not to use bang methods, you can also write `required: true`:
+Compatibility alternative: if you prefer not to use bang methods, you can also write `required: true`:
 
 ```ruby
 query :page, Integer, required: true
@@ -285,7 +298,16 @@ Notes:
 You can also opt an action out of OpenAPI generation from either `doc` or `doc_dry`:
 
 ```ruby
-openapi false
+doc(openapi: false) { }
+doc_dry(:index, openapi: false)
+```
+
+Or inside the block:
+
+```ruby
+doc {
+  openapi false
+}
 ```
 
 #### Scope
@@ -475,6 +497,7 @@ query :birthday, Date, error: "birthday error"
 - `transform`
   - Applies one more custom transformation to the **already-coerced value**.
   - Accepts a `Symbol` or a `Proc`.
+  - `transform` does not run when the field does not successfully resolve to a value, such as when it is missing, `nil`, or already rejected by an earlier validation step.
 - `px` / `px_key`
   - Customize the key name used when the parameter is written into `px`.
 - `validate`
@@ -620,7 +643,7 @@ User.schemas(bang: false)
 | `DateTime` | `"2025-10-17T12:30:00Z"` | Rejects invalid datetimes such as `"2025-10-17 25:00:00"` |
 | `Time` | `"2025-10-17T12:30:00Z"` | Follows `ActiveModel::Type::Time`, so the date part becomes `2000-01-01` |
 | `File` | `ActionDispatch::Http::UploadedFile`, `Tempfile`, file-like IO objects | Keeps the object as-is and does not read file contents into memory |
-| `Object` | `Hash`, `ActionController::Parameters`, arbitrary Ruby objects | Passed through for scalar `Object`; nested hashes use object schema resolution |
+| `Object` | `Hash`, `ActionController::Parameters` | Scalar `Object` behaves like `Hash` and rejects non-hash values; nested hashes use object schema resolution |
 | `[Type]` | arrays such as `%w[1 2 3]` for `[Integer]` | Rejects non-array values, and reports item errors like `tags.1` |
 | nested object | `{ profile: { nickname: "neo" } }` | Rejects non-hash values, and reports nested paths like `profile.nickname` |
 
@@ -810,25 +833,18 @@ If you want to override one specific field directly in the DSL, use `error` or `
 ```ruby
 doc {
   query! :page, Integer, error: "choose a page first"
-  query :role, String, validate: -> { false }, error_message: -> { "is not allowed for #{current_user}" }
+  query :role, String, validate: -> { false }, error: -> { "is not allowed for #{current_user}" }
   json data: {
-    birthday!: { type: Date, error_message: ->(error, value) { "#{error}: #{value.inspect}" } }
+    birthday!: { type: Date, error: ->(error, value) { "#{error}: #{value.inspect}" } }
   }
 }
 ```
 
 ## AI Generation Style Guide
 
-When using AI tools to generate Rails controller code, and the change involves parameter validation, type coercion, default values, or similar parameter contracts, these conventions work well with ActionSpec:
+When using AI tools to generate Rails controller code, treat the [AI Agent Quick Reference](#ai-agent-quick-reference) as the source of truth.
 
-- use `doc { }` or `doc("Summary") { }`; do not add the action name, and do not leave a blank line between the `doc` block and the action method
-- use `{ }` blocks inside `doc` as well; prefer them over `do ... end`
-- when a batch has 3 fields or fewer and does not contain nested hashes, prefer a single-line style, for example:
-  - `json data: { type: String, required: true }`
-  - `in_query(name: String, value: String)` (prefer `in_xxx(...)` batch declarations over multiple `xx` DSL lines when possible)
-- use `!` but not `required: true`
-- use `doc_dry`, `scope`, and `transform`、`px(px_key)`、`px.slice` to keep controller concise
-- when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
+The rest of this README documents all supported forms, including compatibility alternatives such as `doc(:action, ...)` and `required: true`, but generated code should follow the quick reference unless the existing application style requires otherwise.
 
 ## What Is Not Implemented Yet
 

data/lib/action_spec/doc/endpoint.rb

@@ -57,11 +57,13 @@ module ActionSpec
 
       def add_param(location_name, field)
         location(location_name).add(field)
+        clear_custom_validation_cache!
       end
 
       def add_body(media_type, field)
         body.add(field)
         (@body_media_types[media_type.to_sym] ||= Location.new(media_type.to_sym)).add(field.copy)
+        clear_custom_validation_cache!
       end
 
       def register_scope(name, compact: nil, compact_blank: nil)
@@ -91,6 +93,7 @@ module ActionSpec
         @body_media_types = other.body_media_types
         @scope_options = other.scope_options
         @body_required = other.body_required?
+        clear_custom_validation_cache!
       end
 
       def copy
@@ -110,8 +113,18 @@ module ActionSpec
       end
 
       def custom_validation?
-        [header, path, query, cookie, body].any?(&:custom_validation?)
+        custom_validation_locations.any?
       end
+
+      def custom_validation_locations
+        @custom_validation_locations ||= [header, path, query, cookie, body].select(&:custom_validation?).freeze
+      end
+
+      private
+
+        def clear_custom_validation_cache!
+          remove_instance_variable(:@custom_validation_locations) if instance_variable_defined?(:@custom_validation_locations)
+        end
     end
 
     class Location
@@ -126,6 +139,7 @@ module ActionSpec
 
       def add(field)
         @fields[field.name] = field
+        clear_custom_validation_cache!
       end
 
       def field(name)
@@ -151,7 +165,17 @@ module ActionSpec
       end
 
       def custom_validation?
-        fields.any?(&:custom_validation?)
+        custom_validation_fields.any?
+      end
+
+      def custom_validation_fields
+        @custom_validation_fields ||= fields.select(&:custom_validation?).freeze
+      end
+
+      private
+
+        def clear_custom_validation_cache!
+          remove_instance_variable(:@custom_validation_fields) if instance_variable_defined?(:@custom_validation_fields)
       end
     end
 

data/lib/action_spec/schema/array_of.rb

@@ -32,7 +32,7 @@ module ActionSpec
       end
 
       def custom_validation?
-        item.custom_validation?
+        @custom_validation ||= item.custom_validation?
       end
     end
   end

data/lib/action_spec/schema/field.rb

@@ -48,7 +48,7 @@ module ActionSpec
       end
 
       def custom_validation?
-        validate.present? || schema.custom_validation?
+        @custom_validation ||= validate.present? || schema.custom_validation?
       end
 
       def add_error(result, path:, type:, value:, context: nil, **options)

data/lib/action_spec/schema/object_of.rb

@@ -38,7 +38,11 @@ module ActionSpec
       end
 
       def custom_validation?
-        fields.any? { |_name, field| field.custom_validation? }
+        custom_validation_fields.any?
+      end
+
+      def custom_validation_fields
+        @custom_validation_fields ||= fields.each_value.select(&:custom_validation?).freeze
       end
 
       private

data/lib/action_spec/schema/type_caster.rb

@@ -17,7 +17,7 @@ module ActionSpec
           return value if value.nil?
 
           normalized = normalize(type)
-          return value if normalized == :object
+          return cast_object(value) if normalized == :object
           return cast_file(value) if normalized == :file
           return cast_boolean(value) if normalized == :boolean
           return cast_integer(value) if normalized == :integer
@@ -67,6 +67,12 @@ module ActionSpec
             raise CastError, :file
           end
 
+          def cast_object(value)
+            return value if value.is_a?(Hash) || value.is_a?(ActionController::Parameters)
+
+            raise CastError, :object
+          end
+
           def cast_integer(value)
             return value if value.is_a?(Integer)
             raise CastError, :integer unless value.is_a?(String) && value.match?(/\A[+-]?\d+\z/)

data/lib/action_spec/schema.rb

@@ -39,7 +39,7 @@ module ActionSpec
 
       def from_definition(definition)
         return Scalar.new(String) if definition.blank?
-        return ArrayOf.new(from_definition(type: definition.first)) if definition.is_a?(Array) && definition.one?
+        return ArrayOf.new(from_definition(definition.first)) if definition.is_a?(Array) && definition.one?
         return ArrayOf.new(from_definition(type: nil)) if definition == []
         return Scalar.new(definition) unless definition.is_a?(Hash)
 
@@ -47,7 +47,7 @@ module ActionSpec
         if definition.key?(:type)
           type = definition[:type]
           options = definition.slice(*OPTION_KEYS)
-          return ArrayOf.new(from_definition(type: type.first), options) if type.is_a?(Array) && type.one?
+          return ArrayOf.new(from_definition(type.first), options) if type.is_a?(Array) && type.one?
           return ArrayOf.new(from_definition(type: nil), options) if type == []
           if type.is_a?(Hash)
             return Scalar.new(Object, options) if type.empty?

data/lib/action_spec/validator/runner.rb

@@ -25,14 +25,6 @@ module ActionSpec
 
         attr_reader :endpoint, :controller, :coerce
 
-        BUILT_IN_GROUPS = {
-          path: ->(request) { request.path },
-          query: ->(request) { request.query },
-          body: ->(request) { request.body },
-          headers: ->(request) { request.header },
-          cookies: ->(request) { request.cookie }
-        }.freeze
-
         def merge_body!(result)
           if endpoint.request.body_required? && body_source.blank?
             result.add_error("body", :required)
@@ -101,14 +93,15 @@ module ActionSpec
           field.name
         end
 
-      def apply_custom_validations!(result)
-        return unless endpoint.request.custom_validation?
+        def apply_custom_validations!(result)
+          return unless endpoint.request.custom_validation?
 
-        with_controller_px(result.px) do
-          BUILT_IN_GROUPS.each do |location, group_reader|
-            validate_group!(
+          with_controller_px(result.px) do
+            endpoint.request.custom_validation_locations.each do |group|
+              location = group.name
+              validate_group!(
                 result,
-                group_reader.call(endpoint.request),
+                group,
                 values: result.px.scope.fetch(location),
                 location:
               )
@@ -119,9 +112,7 @@ module ActionSpec
         def validate_group!(result, group, values:, location:)
           return unless group.custom_validation?
 
-          group.fields.each do |field|
-            next unless field.custom_validation?
-
+          group.custom_validation_fields.each do |field|
             key = storage_key(field, location)
             next unless values.key?(key)
 
@@ -144,8 +135,7 @@ module ActionSpec
             return unless value.is_a?(Hash)
 
             source = value.with_indifferent_access
-            schema.fields.each_value do |field|
-              next unless field.custom_validation?
+            schema.custom_validation_fields.each do |field|
               next unless source.key?(field.output_name)
 
               validate_field!(field, source[field.output_name], result:, path: [*path, field.name])
@@ -167,8 +157,7 @@ module ActionSpec
             return unless value.is_a?(Hash)
 
             source = value.with_indifferent_access
-            schema.fields.each_value do |field|
-              next unless field.custom_validation?
+            schema.custom_validation_fields.each do |field|
               next unless source.key?(field.output_name)
 
               validate_field!(field, source[field.output_name], result:, path: [*path, field.name])

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "1.6.0"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - zhandao