permittable 0.10.0 → 0.11.1

data/lib/permittable/audit.rb

@@ -15,6 +15,11 @@ module Permittable
   #   bin/rails permittable:audit[strict]   # ...and exit 1 if a write action
   #                                         #    is unguarded (a CI gate)
   #
+  # What is not the app's to guard — ActiveStorage's direct uploads, a
+  # catch-all 404 — is left out with Permittable.audit_ignore, and every
+  # controller whose source is outside Rails.root is left out by default.
+  # Either way it leaves the counts and [strict], never the report.
+  #
   # Plain Ruby over the frozen registry and a list of route descriptors (the
   # same `{ controller:, action:, verb:, path: }` shape OpenAPI.rails_routes
   # produces, plus the optional `route:` it tags each one with), so it is
@@ -30,6 +35,14 @@ module Permittable
     # is usually fine; a POST without one is the finding.
     BODY_VERBS = %w[post put patch].freeze
 
+    # Why an entry is left out of the counts, keyed as Entry#ignored holds it,
+    # with the heading its section of the report carries. Listed in this
+    # order: what the app chose to ignore first, then what it got by default.
+    IGNORE_REASONS = {
+      configured: "Ignored by Permittable.audit_ignore (left out of the counts above):",
+      outside_root: "Ignored as outside the app root (set Permittable.audit_ignore_outside_root = false to audit them):"
+    }.freeze
+
     # One routed action, paired with the rule a request for it would resolve
     # through (nil when nothing covers it — including when the controller
     # never included the concern, which is exactly the case worth finding).
@@ -37,8 +50,10 @@ module Permittable
     # `missing_action` marks a route to an action the controller does not
     # define — see Audit.missing_action?. `route` identifies the route the
     # path came from (nil for a hand-built descriptor, which is then its own
-    # route); see `summary`.
-    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, keyword_init: true) do
+    # route); see `summary`. `ignored` is why the entry is left out of the
+    # counts — a key of IGNORE_REASONS — or nil when it is audited.
+    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, :ignored,
+                       keyword_init: true) do
       def covered?
         !rule.nil?
       end
@@ -47,6 +62,10 @@ module Permittable
         missing_action == true
       end
 
+      def ignored?
+        !ignored.nil?
+      end
+
       # The mode this action would actually run in, rule-level declaration
       # first and the app-wide default behind it.
       def mode
@@ -69,25 +88,137 @@ module Permittable
     # Every routed action of every given controller, sorted for stable output.
     # Pass ALL controllers, not just the ones including Permittable — a
     # controller that never included it is unguarded, which is the point.
-    def entries(controllers:, routes:)
+    #
+    # Ignored actions are returned too, marked with why (Entry#ignored):
+    # `ignore:` is the Permittable.audit_ignore list, and `root:` the app
+    # root a controller's source must be inside (see app_root; nil ignores
+    # nothing on that ground). Both default to the app's own configuration,
+    # as `mode` does.
+    def entries(controllers:, routes:, ignore: Permittable.audit_ignore, root: app_root)
       routes = routes.to_a
-      controllers.flat_map { |controller| controller_entries(controller, routes) }
+      controllers.flat_map { |controller| controller_entries(controller, routes, ignore: ignore, root: root) }
                  .sort_by { |entry| [entry.controller, entry.path, entry.verb.to_s] }
     end
 
-    def controller_entries(controller, routes)
+    # The app's own choice outranks the default: a controller that is both
+    # configured and outside the root is reported as configured, so its entry
+    # counts as matched (see unmatched_ignores) — the README's own example
+    # names ActiveStorage, which the default already covers. The location is
+    # looked up once per controller, not once per route.
+    def controller_entries(controller, routes, ignore: Permittable.audit_ignore, root: app_root)
       key = OpenAPI.controller_key(controller) || controller.inspect
       missing = missing_lookup(controller)
+      outside = :outside_root if outside_root?(controller, root)
       routes.select { |route| route[:controller].to_s == key }.map do |route|
         action = route[:action].to_s
         Entry.new(controller: key, action: action, verb: route[:verb], path: route[:path],
                   rule: rule_for(controller, action), missing_action: missing[action],
-                  route: route[:route])
+                  route: route[:route], ignored: configured_ignore(key, action, ignore) || outside)
+      end
+    end
+
+    # Why `controller` — or one of its actions — is left out of the audit and
+    # of permittable:generate: :configured (Permittable.audit_ignore names the
+    # controller, or "controller#action"), :outside_root, or nil. The
+    # generator asks per action; see Generator.targets.
+    def ignore_reason(controller, action = nil, ignore: Permittable.audit_ignore, root: app_root)
+      key = OpenAPI.controller_key(controller) || controller.inspect
+      configured_ignore(key, action, ignore) || (:outside_root if outside_root?(controller, root))
+    end
+
+    def configured_ignore(key, action, ignore)
+      :configured if ignore.include?(key) || (action && ignore.include?("#{key}##{action}"))
+    end
+
+    # The ignore entries no routed action answers to — a controller that is
+    # not routed, an action it does not route, or a typo of either. Ignored
+    # entries count as matches: the question is whether the entry names
+    # something, not whether it was the only reason that something was
+    # ignored.
+    def unmatched_ignores(entries, ignore: Permittable.audit_ignore)
+      ignore.reject do |item|
+        key, action = item.split("#", 2)
+        entries.any? { |entry| entry.controller == key && (action.nil? || entry.action == action) }
+      end
+    end
+
+    # The root a controller's source must be inside to be audited:
+    # Rails.root, unless Permittable.audit_ignore_outside_root is off — or nil
+    # without Rails, where there is no app to be outside of.
+    def app_root
+      return nil unless Permittable.audit_ignore_outside_root
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:root)
+
+      ::Rails.root&.to_s
+    end
+
+    # Whether `controller` is an engine's or a gem's rather than the app's:
+    # its source is outside `root`, or inside a directory gems are installed
+    # in — `bundle config path vendor/bundle`, which CI caches and Docker
+    # images commonly use, puts every gem inside the app's root, and
+    # ActiveStorage's controller is no more the app's for being there. A gem
+    # directory that holds the root itself (a GEM_HOME set to the app, or to
+    # a parent of it) says nothing about which side a file is on, so it is
+    # not consulted — otherwise every app controller would read as a gem's
+    # and [strict] would pass on nothing. A controller that cannot be located
+    # is audited: for a gate, a false alarm beats a missed endpoint.
+    def outside_root?(controller, root)
+      return false if root.nil?
+
+      path = source_path(controller)
+      return false if path.nil?
+
+      !within?(path, root) || Gem.path.any? { |dir| within?(path, dir) && !within?(root, dir) }
+    end
+
+    # Where `controller` is defined: its constant's own definition (the
+    # `class` line — reopening a gem's controller in app/ does not move it),
+    # or, for a class whose constant cannot be found, the first of its own
+    # methods that has a location. nil when neither says.
+    #
+    # A constant that is registered for autoload but not loaded reports the
+    # `autoload` call instead — never the case here, since only loaded
+    # classes have descendants to audit.
+    def source_path(controller)
+      name = controller.name if controller.respond_to?(:name)
+      located = begin
+        # [] for a constant defined in C, so `first` is nil there too.
+        Object.const_source_location(name)&.first if name.is_a?(String) && !name.empty?
+      rescue NameError
+        nil
+      end
+      located || method_source_path(controller)
+    end
+
+    def method_source_path(controller)
+      return nil unless controller.is_a?(Module)
+
+      methods = controller.instance_methods(false) + controller.private_instance_methods(false)
+      methods.lazy.filter_map { |name| controller.instance_method(name).source_location&.first }.first
+    end
+
+    # Whether `path` is `dir` or inside it, compared both as written and with
+    # symlinks resolved: Rails.root is a realpath, and on macOS a tmpdir under
+    # /var is really under /private/var — either side alone can disagree with
+    # the other, and an app controller misread as outside the root would drop
+    # out of [strict]. A form that cannot be resolved (a path that does not
+    # exist) is compared as written only.
+    def within?(path, dir)
+      [[File.expand_path(path), File.expand_path(dir)], [realpath(path), realpath(dir)]].any? do |file, base|
+        file && base && (file == base || file.start_with?(File.join(base, "")))
       end
     end
 
+    def realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    end
+
     # action => missing?, answered once per action: a `via: :all` route is
-    # five entries for one action, and each resolver call builds a controller.
+    # up to five entries for one action (fewer when an earlier, unconstrained
+    # route already answers some of its verbs on that path, see
+    # OpenAPI.drop_shadowed), and each resolver call builds a controller.
     # The action list is read once per controller, not once per route.
     def missing_lookup(controller)
       listed = listed_actions(controller)
@@ -144,20 +275,64 @@ module Permittable
     # kind is in no summary bucket, so without this it would vanish from the
     # report's conclusions. Catch-all rules declare no actions, so they never
     # appear here.
+    #
+    # Judged per RULE, not per class: permittable_contracts is a
+    # class_attribute, so a subclass carries every rule its parent declared,
+    # and judging each class alone listed a shared base (routed to nothing)
+    # and every subclass routed to a different slice of its actions. A rule's
+    # action is stale only when NO controller carrying that rule reaches it —
+    # the class that declared it, or any descendant among `controllers:` — and
+    # it is listed once, under the declaring class, where the fix is made.
+    # Counting only the rules a class added itself would not do: the shared
+    # base still has no routes. Shadowing is not judged: an action some
+    # carrier reaches is not stale, even if that carrier declares its own rule
+    # for it, just as a rule redeclared within one class never was.
     def stale(controllers:, routes:)
       routes = routes.to_a
-      controllers.each_with_object({}) do |controller, found|
+      reaches = Hash.new { |memo, controller| memo[controller] = reach_lookup(controller, routes) }
+      carriers(controllers).each_with_object({}) do |(rule, held_by), found|
+        declarer = declaring_class(held_by.first, rule)
+        holders = held_by | [declarer]
+        left = rule[:actions].reject { |action| holders.any? { |controller| reaches[controller][action] } }
+        next if left.empty?
+
+        key = OpenAPI.controller_key(declarer) || declarer.inspect
+        found[key] = (found.fetch(key, []) + left).uniq
+      end
+    end
+
+    # rule => the given controllers carrying it, in first-seen order. Keyed by
+    # IDENTITY: permit_params hands a subclass its parent's rule objects, while
+    # two classes declaring the same fields build equal but distinct rules.
+    def carriers(controllers)
+      controllers.each_with_object({}.compare_by_identity) do |controller, held|
         next unless controller.respond_to?(:permittable_contracts)
 
-        key = OpenAPI.controller_key(controller) || controller.inspect
-        routed = routes.select { |route| route[:controller].to_s == key }.map { |route| route[:action].to_s }
-        declared = controller.permittable_contracts.flat_map { |rule| rule[:actions] }.uniq
-        missing = missing_lookup(controller)
-        left = declared.select { |action| !routed.include?(action) || missing[action] }
-        found[key] = left unless left.empty?
+        controller.permittable_contracts.each { |rule| (held[rule] ||= []) << controller }
       end
     end
 
+    # action => whether a request for it reaches `controller`: routed there,
+    # and not to an action Rails would 404. Lazy, so the resolver is asked
+    # only about actions some contract declares.
+    def reach_lookup(controller, routes)
+      key = OpenAPI.controller_key(controller) || controller.inspect
+      routed = routes.select { |route| route[:controller].to_s == key }.to_set { |route| route[:action].to_s }
+      missing = missing_lookup(controller)
+      Hash.new { |memo, action| memo[action] = routed.include?(action) && !missing[action] }
+    end
+
+    # The highest ancestor still carrying `rule` — the class whose
+    # permit_params declared it, whether or not it was among `controllers:`.
+    def declaring_class(controller, rule)
+      controller = controller.superclass while controller.respond_to?(:superclass) && carries?(controller.superclass, rule)
+      controller
+    end
+
+    def carries?(controller, rule)
+      controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any? { |held| held.equal?(rule) }
+    end
+
     # The numbers worth putting in a CI log. `uncovered_with_body` is the one
     # that should be zero; `unguarded_models` counts covered actions whose
     # rule declares no `model:`, so no schema-drift guard runs for them.
@@ -172,8 +347,11 @@ module Permittable
     # An action the controller does not define takes no body, and a contract
     # left on one guards nothing, so it is counted as `missing_actions` and in
     # no other bucket — the buckets stay disjoint and still add up to `actions`.
+    #
+    # An ignored entry (Entry#ignored) is in none of the counts, so it never
+    # fails [strict]; `format` lists it in a section of its own instead.
     def summary(entries)
-      entries = routed(entries)
+      entries = routed(entries.reject(&:ignored?))
       found, missing = entries.partition { |e| !e.missing_action? }
       {
         actions: entries.length,
@@ -196,16 +374,28 @@ module Permittable
     end
 
     # The human-readable report: one block per controller, then the summary,
-    # then anything stale.
-    def format(entries, stale: {})
-      return "Permittable audit: no routed actions to report.\n" if entries.empty?
-
-      out = entries.group_by(&:controller).map { |key, group| controller_block(key, group) }
-      out << summary_lines(summary(entries), rows: entries.length)
+    # then anything stale. The table and the summary cover the audited
+    # entries; what was ignored follows in sections of its own, then any
+    # ignore entry that matched nothing — `unmatched` defaults to checking
+    # Permittable.audit_ignore, the list `entries` defaults to.
+    #
+    # With no routed action at all there is no table or summary, but the
+    # stale and unmatched sections still follow: that is when a contract no
+    # route reaches, or an ignore entry naming nothing, most needs saying.
+    def format(entries, stale: {}, unmatched: unmatched_ignores(entries))
+      ignored, audited = entries.partition(&:ignored?)
+      out = entries.empty? ? ["Permittable audit: no routed actions to report."] : table_lines(audited)
       out << stale_lines(stale) unless stale.empty?
+      out << ignored_lines(ignored) unless ignored.empty?
+      out << unmatched_lines(unmatched) unless unmatched.empty?
       "#{out.join("\n")}\n"
     end
 
+    def table_lines(entries)
+      entries.group_by(&:controller).map { |key, group| controller_block(key, group) } <<
+        summary_lines(summary(entries), rows: entries.length)
+    end
+
     def controller_block(key, group)
       rows = group.map do |entry|
         "  #{entry.verb.to_s.upcase.ljust(6)} #{entry.path.ljust(34)} #{entry.action.ljust(12)} #{status(entry)}"
@@ -242,9 +432,14 @@ module Permittable
     # say WHY they differ: an optional segment's variants are the usual
     # reason, but two concatenated route lists sharing a controller, action
     # and index collapse the same way.
+    #
+    # Each line agrees with its own count: "1 of those accepts", "1 covered
+    # action declares ... for it". `rows` needs no singular — it only prints
+    # when it exceeds the route count, so it is at least 2.
     def summary_lines(counts, rows: counts[:actions])
       body = counts[:uncovered_with_body]
       missing = counts[:missing_actions]
+      models = counts[:unguarded_models]
       # Its own bucket, so the head line still adds up to the route count.
       not_found = ", #{missing} not found (Rails 404s #{missing == 1 ? 'it' : 'them'})" unless missing.zero?
       listed = " in #{rows} rows" unless rows == counts[:actions]
@@ -253,9 +448,10 @@ module Permittable
         "#{counts[:actions]} routed action#{'s' unless counts[:actions] == 1}#{listed}: " \
         "#{counts[:enforced]} enforced, #{counts[:monitored]} in monitor mode, " \
         "#{counts[:uncovered]} without a contract#{not_found}",
-        "  #{body} of those accept a request body#{' — untrusted input reaches the action unchecked' unless body.zero?}",
-        "  #{counts[:unguarded_models]} covered action#{'s' unless counts[:unguarded_models] == 1} " \
-        "declare no model:, so no schema-drift guard runs for them"
+        "  #{body} of those accept#{'s' if body == 1} a request body" \
+        "#{' — untrusted input reaches the action unchecked' unless body.zero?}",
+        "  #{models} covered action#{models == 1 ? ' declares' : 's declare'} no model:, " \
+        "so no schema-drift guard runs for #{models == 1 ? 'it' : 'them'}"
       ].join("\n")
     end
 
@@ -264,5 +460,26 @@ module Permittable
       "\nContracts declared for actions no route reaches or Rails would 404 (renamed or deleted?):\n" \
         "#{pairs.map { |pair| "  #{pair}" }.join("\n")}"
     end
+
+    # One section per reason, in IGNORE_REASONS order, and one line per
+    # controller#action with every verb it is routed on: a `via: :all`
+    # catch-all is one line rather than five rows, so what was left out stays
+    # visible without crowding the table it was left out of.
+    def ignored_lines(ignored)
+      IGNORE_REASONS.filter_map do |reason, heading|
+        group = ignored.select { |entry| entry.ignored == reason }
+        next if group.empty?
+
+        verbs = group.group_by { |entry| "#{entry.controller}##{entry.action}" }
+                     .transform_values { |list| list.map { |entry| entry.verb.to_s.upcase }.uniq.join(", ") }
+        width = verbs.keys.map(&:length).max
+        "\n#{heading}\n#{verbs.map { |pair, list| "  #{pair.ljust(width)}  #{list}" }.join("\n")}"
+      end.join("\n")
+    end
+
+    def unmatched_lines(unmatched)
+      "\nPermittable.audit_ignore entries that match no routed action (a typo, or a route since removed?):\n" \
+        "#{unmatched.map { |item| "  #{item}" }.join("\n")}"
+    end
   end
 end

data/lib/permittable/authored_values.rb

@@ -7,15 +7,23 @@ module Permittable
   #     its own `transform:` — see permittable_transform below for exactly
   #     which field that is and why. A SUB-FIELD's own transform: still
   #     runs, so what gets stored is what an equivalent request would
-  #     produce.
+  #     produce — for a default:, and, under a transforming array, only
+  #     where an array-level validate: reads its output. An example: is
+  #     read `as_sent`, which is what gets stored: no transform at any
+  #     depth, no sub-field default filled in and no array-level validate:.
+  #     When an array-level validate: exists somewhere in it, it is read
+  #     once more first, like a default, to VALIDATE it as a request would
+  #     be (see ContractBuilder, which decides). An example documents what a
+  #     client SENDS, so it must not be read through app code that reshapes
+  #     the value into what the action receives.
   #   * violations carry no `message:` — they become an ArgumentError for
   #     the contract's author, not a response for a client, and I18n may not
   #     be loaded yet.
   class AuthoredValues
     include Permittable
 
-    def self.read_array(field, value)
-      new.read_array(field, value)
+    def self.read_array(field, value, as_sent: false)
+      new.read_array(field, value, as_sent: as_sent)
     end
 
     def self.summary(violations)
@@ -23,9 +31,11 @@ module Permittable
     end
 
     # [value as a request would get it, violations]
-    def read_array(field, value)
+    def read_array(field, value, as_sent: false)
       violations = []
       @field = field
+      @as_sent = as_sent
+      @read_by_validate = fields_under_validate(field) if field[:transform]
       read = permittable_check_array(field, value, path: field[:name].to_s, unknown: :ignore, violations: violations)
       [read, violations]
     end
@@ -45,17 +55,67 @@ module Permittable
     # identical value silently diverge (and the exported OpenAPI default,
     # which reads this same value, documents one the server never produces).
     #
-    # When @field itself has a transform:, its result is discarded anyway
-    # (validate_array_authored_value! stores the value AS AUTHORED instead —
-    # see its comment), so nothing inside its subtree is worth reading
-    # transformed: suppressing every nested call too keeps that walk free of
-    # app code, exactly as a scalar default's cast-only check already is.
+    # When @field itself has a transform:, it never runs here either way and
+    # its result is discarded anyway (validate_array_authored_value! stores
+    # the value AS AUTHORED instead — see its comment). A sub-field's
+    # transform: output is another matter: a request runs it, then the
+    # array-level `validate:` on that result, and only then the array's own
+    # transform. So a `validate:` that reads `i[:tags].is_a?(Array)` must be
+    # handed the transformed `tags`, or a contract every request satisfies
+    # fails at class load. But a transform: is app code (`Account.find`), so
+    # under such an array it runs ONLY where its output is consumed: for a
+    # field below an array declaring `validate:` (the walked array counts),
+    # not merely somewhere in the same subtree, where a `validate:` on a
+    # sibling branch reads nothing of it. Without an own transform: of its
+    # own, @field's read is what gets stored, so every sub-field's runs.
+    #
+    # `as_sent` (the stored read of an example:) runs none, at any depth.
     def permittable_transform(field, value)
-      return value if @field[:transform] || field.equal?(@field)
+      return value if @as_sent || field.equal?(@field)
+      return value if @field[:transform] && !@read_by_validate.key?(field)
 
       super
     end
 
+    # The fields below `field` whose output an array's `validate:` sees: all
+    # those under an array that declares one, counting `field` itself, by
+    # identity (the walker hands the very field hashes it was given).
+    def fields_under_validate(field, found = {}.compare_by_identity, under_validate: false)
+      under_validate ||= field[:kind] == :array && field[:validate]
+      Array(field[:fields]).each do |sub|
+        found[sub] = true if under_validate
+        fields_under_validate(sub, found, under_validate: under_validate)
+      end
+      found
+    end
+
+    # Nor does it run an array-level validate:, which expects the transformed
+    # sub-fields a request hands it. The validating read has already run it
+    # on exactly those, so the stored read, which would hand it the
+    # untransformed ones, must not (it could raise on a shape it never sees).
+    def permittable_array_validator(field)
+      super unless @as_sent
+    end
+
+    # What a client sends has no defaults filled in: an omitted sub-field
+    # stays omitted, at any depth, so the published example does not show a
+    # value (`cents: 0`) that no client sends. The walker fills them in; drop
+    # exactly what it filled, by the walker's own absence rule.
+    def permittable_check_hash(fields, hash, **)
+      result = super
+      return result unless @as_sent
+
+      fields.each do |field|
+        key = field[:name].to_s
+        next unless field.key?(:default)
+        next unless permittable_absent?(permittable_normalized(field, hash[key]), hash, key)
+        next if permittable_explicit_null?(field, hash, key)
+
+        result.delete(key)
+      end
+      result
+    end
+
     def permittable_violation(_field, param, code)
       { param: param, code: code.to_s }
     end

data/lib/permittable/column_guard.rb

@@ -33,8 +33,9 @@ module Permittable
     # `types:` teaches the error message: a Symbol/String applies to every
     # listed field, a Hash maps field => type. The raised ArgumentError then
     # appends a ready-to-paste migration command. `allowed:` maps field =>
-    # its `in:`, for the fields that declare one; only the enum rule reads it.
-    def ensure_columns_on!(label, klass, *fields, types: nil, check_types: false, allowed: nil)
+    # its `in:`, for the fields that declare one, and `transformed:` lists
+    # the fields that declare a `transform:`; only the enum rule reads them.
+    def ensure_columns_on!(label, klass, *fields, types: nil, check_types: false, allowed: nil, transformed: nil)
       return false unless schema_reachable?(klass)
 
       fields.flatten.compact.each do |field|
@@ -44,7 +45,7 @@ module Permittable
                 "#{column_migration_hint(klass, field, types)}"
         end
 
-        ensure_column_type!(label, klass, field, types, allowed) if check_types
+        ensure_column_type!(label, klass, field, types, allowed, transformed: transformed) if check_types
       end
       true
     end
@@ -54,7 +55,7 @@ module Permittable
     # TYPE_GROUPS) and stays silent unless both sides are known, so it can
     # only fire on a genuine cross-family mismatch — a contract still saying
     # :datetime after the column became a string, say.
-    def ensure_column_type!(label, klass, field, types, allowed = nil)
+    def ensure_column_type!(label, klass, field, types, allowed = nil, transformed: nil)
       declared = types.is_a?(Hash) ? types[field.to_sym] : types
       column = klass.columns_hash[field.to_s]
       return unless declared && column
@@ -63,7 +64,10 @@ module Permittable
       enum = enum_attribute?(klass, field)
       # Checked before the column's type, which an enum's contract does not
       # depend on: see ensure_enum_contract!.
-      return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym]) if enum && wanted == :text
+      if enum && wanted == :text
+        return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym],
+                                     transformed: Array(transformed).include?(field.to_sym))
+      end
 
       # `column.type` is nil for a SQL type the adapter does not recognise
       # (a PostGIS geometry column without the extension loaded, a custom
@@ -107,25 +111,31 @@ module Permittable
     # Accepted means what the enum's cast accepts: every name, plus every
     # stored value that is a String (a string-backed enum takes `"p"` for
     # `pro:` as readily as `"pro"`). An integer-backed enum's stored values
-    # are not accepted — a request carries `"0"`, which maps to nothing. A
-    # Range, or anything else without a finite list, cannot be checked, so it
-    # is refused rather than trusted.
+    # are not accepted — a request carries `"0"`, which maps to nothing —
+    # unless the field declares a `transform:`, which runs after `in:` and is
+    # how permittable:generate's TODO maps them back to names. Only the stored
+    # integers are admitted that way; the transform is app code, trusted to
+    # do what the TODO spells. A Range, or anything else without a finite
+    # list, cannot be checked, so it is refused rather than trusted.
     #
     # Only `enum` is recognised. The attribute API (`attribute :x, :datetime`
     # over a string column) is left compared against the column by choice:
     # an enum's mapping says exactly which strings are valid, an attribute
     # override says nothing a contract could be checked against.
-    def ensure_enum_contract!(label, klass, field, declared, listed)
+    def ensure_enum_contract!(label, klass, field, declared, listed, transformed: false)
       problem =
         if listed.nil?
           "declared :#{declared} without an in:"
         elsif listed.is_a?(Range) || !listed.respond_to?(:to_a)
           "declared :#{declared} with an in: that does not list its values"
         else
-          stray = listed.to_a - enum_values(klass, field)
+          accepted = enum_values(klass, field)
+          accepted += stored_integers(klass, field) if transformed
+          stray = listed.to_a - accepted
           return if stray.empty?
 
-          "declared :#{declared} with an in: listing values it would refuse: #{stray.map(&:inspect).join(', ')}"
+          "declared :#{declared} with an in: listing values it would refuse: #{stray.map(&:inspect).join(', ')}" \
+            "#{stored_integer_hint(klass, field, stray, transformed)}"
         end
 
       raise ArgumentError,
@@ -139,6 +149,16 @@ module Permittable
       mapping.keys.map(&:to_s) + mapping.values.grep(String)
     end
 
+    def stored_integers(klass, field)
+      klass.defined_enums[field.to_s].values.grep(Integer).map(&:to_s)
+    end
+
+    def stored_integer_hint(klass, field, stray, transformed)
+      return "" if transformed || !stray.intersect?(stored_integers(klass, field))
+
+      " (a stored integer is accepted only beside a transform: mapping it back to its name)"
+    end
+
     # `Order.statuses.keys` when the enum's plural reader exists, and the
     # always-valid `defined_enums["..."]` spelling when it does not (a name
     # that is not a Ruby identifier, a duck-typed model).

data/lib/permittable/contract.rb

@@ -62,10 +62,38 @@ module Permittable
           super(fields, hash, path: path, unknown: unknown, top_level: false, violations: violations)
         end
 
+        # unknown: :log warns through `logger`, and a controller gets one from
+        # ActionController. This host has none, so :log used to drop the keys
+        # without a word, exactly like :ignore. Rails.logger is read on every
+        # call, not at definition: contracts are usually constants, loaded
+        # before an app's initializers may have assigned it. With no Rails
+        # (a script, a job, a CSV import) the warning goes to $stderr rather
+        # than nowhere, since a :log that cannot log is :ignore by another
+        # name. Defining the contract does not raise for a missing logger:
+        # whether one exists is only known when the contract is called.
+        #
+        # The fallback Logger is built on every call, not memoized: #call!
+        # makes a new host per call, so an instance memo never applied, and a
+        # class-level one would capture $stderr once, hiding a later
+        # reassignment (a test's capture, a daemonized process's redirect).
+        def logger
+          return ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+          ::Logger.new($stderr)
+        end
+
         # Instrumentation payload label (anonymous classes have no name).
         def permittable_controller_name
           "Permittable::Contract"
         end
+
+        # ... and its action: the host has no action_name, so the payload's
+        # `action` (documented as a String) and the log lines that name the
+        # action would be nil. A Contract has one entry point, the same
+        # "call" #call! passes to permitted_params.
+        def permittable_action_name
+          ACTION
+        end
       end
       @host_class.permit_params(root: root, unknown: unknown, model: model, mode: :enforce, desc: desc, &)
     end
@@ -118,9 +146,30 @@ module Permittable
 
     def normalize_input(input)
       return {} if input.nil?
-      return input if input.is_a?(Hash) || input.respond_to?(:to_unsafe_h)
+      return input if input.respond_to?(:to_unsafe_h)
+      return unwrap_parameters(input) if input.is_a?(Hash)
 
       raise ArgumentError, "#{LABEL}: Contract#call expects a Hash (got #{input.class})"
     end
+
+    # A controller's params reach the concern as ActionController::Parameters
+    # and are converted deeply by to_unsafe_h. A service object is usually
+    # handed a slice of them inside a plain Hash — `CreateUser.call(user:
+    # params[:user])` — and nothing converted those: a Parameters value is
+    # not a Hash, so a root read it as invalid_type (400), a nested block or
+    # :json field likewise (422). Each one is converted here, the way
+    # to_unsafe_h converts the whole. Only what holds one is copied.
+    def unwrap_parameters(value)
+      case value
+      when Hash
+        unwrapped = value.transform_values { |v| unwrap_parameters(v) }
+        unwrapped.each_value.zip(value.each_value).all? { |new, old| new.equal?(old) } ? value : unwrapped
+      when Array
+        unwrapped = value.map { |v| unwrap_parameters(v) }
+        unwrapped.zip(value).all? { |new, old| new.equal?(old) } ? value : unwrapped
+      else
+        value.respond_to?(:to_unsafe_h) ? value.to_unsafe_h : value
+      end
+    end
   end
 end