permittable 0.1.2 → 0.3.0

data/lib/permittable.rb

@@ -79,6 +79,15 @@ require "permittable/filter_parameter_registry"
 # renders 400, field violations 422. Every violation also instruments
 # "invalid_parameters.permittable" so failures can be dashboarded.
 #
+# Violation MESSAGES stay machine-first (the code is the contract), but a
+# field can attach human-readable copy with `message:` — one String for every
+# code (`message: "must be a valid email"`) or a Hash per code
+# (`message: { missing: "is required", format: "must be a valid email" }`).
+# A resolved message rides into the detail entry as `message:` and replaces
+# the "(code)" rendering in the exception's summary line; codes without a
+# message keep the bare shape, so nothing changes for contracts that don't
+# opt in. `violate!` in finalize accepts the same via `message:`.
+#
 # `sensitive: true` registers the field name with
 # Permittable.filter_parameter_registry (swappable — a host gem can point it
 # at its own registry), consulted at filter time by the proc
@@ -304,9 +313,9 @@ module Permittable
   # declaration is validated eagerly: a bad contract is a programmer error and
   # should fail at class load, not at request time.
   class ContractBuilder
-    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform].freeze
-    NESTED_OPTS = %i[virtual sensitive].freeze
-    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform].freeze
+    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example].freeze
+    NESTED_OPTS = %i[virtual sensitive message desc].freeze
+    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example].freeze
 
     attr_reader :finalizer
 
@@ -359,7 +368,9 @@ module Permittable
       validate_length!(name, field[:length]) if field.key?(:length)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
-      validate_array_default!(field) if field.key?(:default)
+      validate_array_authored_value!(field, :default) if field.key?(:default)
+      validate_array_authored_value!(field, :example) if field.key?(:example)
+      validate_message!(field)
       @fields << field
     end
 
@@ -371,15 +382,16 @@ module Permittable
         raise ArgumentError, "#{LABEL}: :#{name} takes a type OR a nested block, not both" if type
 
         assert_opts!(name, opts, NESTED_OPTS)
-        @fields << { name: name, kind: :nested, required: required,
-                     fields: nested_fields!(name, &block), **opts }
+        field = { name: name, kind: :nested, required: required,
+                  fields: nested_fields!(name, &block), **opts }
+        validate_message!(field)
       else
         assert_opts!(name, opts, SCALAR_OPTS)
         field = { name: name, kind: :scalar, required: required,
                   type: scalar_type!(name, type || :string), **opts }
         validate_scalar_opts!(field)
-        @fields << field
       end
+      @fields << field
     end
 
     def field_name!(name)
@@ -431,7 +443,9 @@ module Permittable
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
       resolve_normalizer!(field)
-      validate_default!(field)
+      validate_authored_value!(field, :default)
+      validate_authored_value!(field, :example)
+      validate_message!(field)
     end
 
     # format / length / normalize reason about characters; on any other
@@ -469,28 +483,49 @@ module Permittable
       end
     end
 
-    # A default must satisfy the field's own contract — catching a bad
-    # default at class load beats shipping it to every request.
-    def validate_default!(field)
-      return unless field.key?(:default)
+    # An authored value (`default:`, or a documentation `example:`) must
+    # satisfy the field's own contract — catching a lie at class load beats
+    # shipping it to every request (or publishing it in generated docs).
+    def validate_authored_value!(field, opt)
+      return unless field.key?(opt)
 
-      status, code = Coercion.check_scalar(field, field[:default])
+      status, code = Coercion.check_scalar(field, field[opt])
       return if status == :ok
 
-      raise ArgumentError, "#{LABEL}: :default for field :#{field[:name]} violates its own contract (#{code})"
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
     end
 
-    def validate_array_default!(field)
-      default = field[:default]
-      raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} must be an Array" unless default.is_a?(Array)
+    def validate_array_authored_value!(field, opt)
+      value = field[opt]
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
       return unless field[:of]
 
-      default.each do |element|
+      value.each do |element|
         status, code = Coercion.cast(field[:of], element)
         next if status == :ok
 
-        raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
+      end
+    end
+
+    # `message:` customizes what the client reads for a violation on this
+    # field: one String covering every code, or a Hash of code => String
+    # (codes without an entry keep the default rendering). Keys are
+    # normalized to Symbols here so request-time resolution is a plain
+    # lookup.
+    def validate_message!(field)
+      spec = field[:message]
+      return if spec.nil?
+      return if spec.is_a?(String)
+
+      valid_hash = spec.is_a?(Hash) && !spec.empty? &&
+                   spec.all? { |code, text| (code.is_a?(Symbol) || code.is_a?(String)) && text.is_a?(String) }
+      unless valid_hash
+        raise ArgumentError, "#{LABEL}: :message for field :#{field[:name]} must be a String " \
+                             "or a Hash of violation code => String (e.g. { missing: \"is required\" })"
       end
+
+      field[:message] = spec.transform_keys(&:to_sym).freeze
     end
   end
 
@@ -504,9 +539,13 @@ module Permittable
 
     # Records ONE violation and halts the finalize block immediately (the
     # code after a violate! call never runs, so it can assume the checked
-    # invariant). The contract then fails as a normal 422.
-    def violate!(param, code)
-      @violations << { param: param.to_s, code: code.to_s }
+    # invariant). The contract then fails as a normal 422. An optional
+    # message: rides along into the violation detail, same as a field's
+    # `message:` option.
+    def violate!(param, code, message: nil)
+      entry = { param: param.to_s, code: code.to_s }
+      entry[:message] = message.to_s if message
+      @violations << entry
       throw :permittable_finalize_halt
     end
   end
@@ -525,7 +564,9 @@ module Permittable
     #            undeclared keys, at every nesting level.
     #   enforce: false (default) validates lazily on the first
     #            permitted_params call; true validates in a before_action.
-    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &block)
+    #   desc:    documentation only — carried on the rule for exporters
+    #            (Permittable::OpenAPI); the runtime never reads it.
+    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, desc: nil, &block)
       raise ArgumentError, "#{LABEL}: permit_params requires a block declaring the contract fields" unless block
 
       unknown = unknown.to_sym
@@ -541,7 +582,7 @@ module Permittable
 
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
                model: model_class, unknown: unknown, enforce: !!enforce, fields: fields,
-               finalize: builder.finalizer }.freeze
+               finalize: builder.finalizer, desc: desc }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -663,10 +704,27 @@ module Permittable
       "invalid_parameters.permittable",
       controller: permittable_controller_name, action: permittable_action_name, details: violations
     )
-    summary = violations.map { |v| "#{v[:param]} (#{v[:code]})" }.join(", ")
+    summary = violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
     raise InvalidParameters.new("Invalid parameters: #{summary}", details: violations, status: status)
   end
 
+  # One violation detail entry. A field's `message:` (String, or Hash keyed
+  # by code) attaches a human-readable message; entries without one keep
+  # the bare { param:, code: } shape, so existing consumers see no change.
+  def permittable_violation(field, param, code)
+    entry = { param: param, code: code.to_s }
+    message = permittable_message_for(field, code)
+    entry[:message] = message if message
+    entry
+  end
+
+  def permittable_message_for(field, code)
+    spec = field[:message]
+    return spec if spec.nil? || spec.is_a?(String)
+
+    spec[code.to_sym]
+  end
+
   def permittable_run_finalize(finalizer, result, violations)
     runner = FinalizeRunner.new(violations)
     finalized = catch(:permittable_finalize_halt) do
@@ -713,7 +771,7 @@ module Permittable
         if field.key?(:default)
           result[key] = field[:default]
         elsif field[:required]
-          violations << { param: full, code: "missing" }
+          violations << permittable_violation(field, full, "missing")
         end
         next
       end
@@ -733,33 +791,33 @@ module Permittable
         out = field[:transform].call(out) if field[:transform]
         result[key] = out
       else
-        violations << { param: full, code: out }
+        violations << permittable_violation(field, full, out)
       end
     when :nested
       if value.is_a?(Hash)
         result[key] = permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(value),
                                              path: full, unknown: unknown, top_level: false, violations: violations)
       else
-        violations << { param: full, code: "invalid_type" }
+        violations << permittable_violation(field, full, "invalid_type")
       end
     when :array
       if value.is_a?(Array)
         result[key] = permittable_check_array(field, value, path: full, unknown: unknown, violations: violations)
       else
-        violations << { param: full, code: "invalid_type" }
+        violations << permittable_violation(field, full, "invalid_type")
       end
     end
   end
 
   def permittable_check_array(field, value, path:, unknown:, violations:)
     before = violations.length
-    violations << { param: path, code: "length" } if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+    violations << permittable_violation(field, path, "length") if field[:length] && !Coercion.length_ok?(field[:length], value.length)
     out = value.each_with_index.map do |element, index|
       permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
     end
     if field[:validate]
       status, code = Coercion.check_custom(field[:validate], out)
-      violations << { param: path, code: code } unless status == :ok
+      violations << permittable_violation(field, path, code) unless status == :ok
     end
     # Transform only a fully-valid array — a partially-nil one (element
     # violations) would hand user code garbage it never agreed to see.
@@ -770,7 +828,7 @@ module Permittable
   def permittable_check_element(field, element, path, unknown:, violations:)
     if field[:fields]
       unless element.is_a?(Hash)
-        violations << { param: path, code: "invalid_type" }
+        violations << permittable_violation(field, path, "invalid_type")
         return nil
       end
       return permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(element),
@@ -780,7 +838,7 @@ module Permittable
     status, out = Coercion.cast(field[:of], element)
     return out if status == :ok
 
-    violations << { param: path, code: out }
+    violations << permittable_violation(field, path, out)
     nil
   end
 
@@ -820,5 +878,11 @@ module Permittable
   end
 end
 
-# Boot-time integration (filter_parameters registration), Rails apps only
+# Contract exporters — the other readers of the frozen contract registry.
+# Loaded after the module body so OpenAPI can see the concern's own methods.
+require "permittable/json_schema"
+require "permittable/open_api"
+
+# Boot-time integration (filter_parameters registration, the
+# permittable:openapi rake task), Rails apps only
 require "permittable/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -50,7 +50,10 @@ files:
 - lib/permittable/column_guard.rb
 - lib/permittable/error_envelope.rb
 - lib/permittable/filter_parameter_registry.rb
+- lib/permittable/json_schema.rb
+- lib/permittable/open_api.rb
 - lib/permittable/railtie.rb
+- lib/permittable/tasks/openapi.rake
 - lib/permittable/version.rb
 homepage: https://github.com/VSN2015/permittable
 licenses: