permittable 0.11.1 → 0.13.0

data/lib/permittable/field_group.rb

@@ -25,7 +25,8 @@ module Permittable
   #       use UserFields
   #     end
   #
-  #     # PATCH: same fields, nothing mandatory.
+  #     # PATCH: same fields, nothing mandatory, no defaults (a default
+  #     # would reset plan to "free" on every PATCH that omits it).
   #     permit_params :update, root: :user, model: User do
   #       use UserFields, optional: true
   #     end

data/lib/permittable/generator.rb

@@ -43,7 +43,7 @@ module Permittable
     # lists the column. They ride on the column, set by in_rule, so the scan
     # path hands them to column_line without its own methods changing.
     DraftColumn = Struct.new(:name, :type, :null, :default, :default_function, :enum, :enum_integers, :sensitive,
-                             :unread, :rule, :listed, :assigned, keyword_init: true) do
+                             :unread, :rule, :listed, :assigned, :array, :array_default, keyword_init: true) do
       def in_rule(rule, listed: false)
         self.class.new(**to_h, rule: rule, listed: listed)
       end
@@ -554,6 +554,8 @@ module Permittable
     def draft_column(model, column)
       DraftColumn.new(name: column.name, type: column.type, null: column.null,
                       default_function: column.respond_to?(:default_function) && column.default_function,
+                      array: column.respond_to?(:array?) && column.array? == true,
+                      array_default: array_default?(column.default),
                       sensitive: sensitive_role(model, column.name), assigned: assigned?(model, column),
                       **model_facts(model, column))
     end
@@ -1084,9 +1086,11 @@ module Permittable
     # does not parse.
     def column_line(column)
       return "# TODO: #{column.name} #{omitted_note(column)}" if column.sensitive && !column.listed
+      return array_column_line(column) if column.array
 
       type = column.enum ? :string : COLUMN_TYPES[column.type]
       return "# TODO: #{column.name} (#{column.type}) has no contract type — declare it as a nested block or an array" unless type
+      return json_array_todo(column) if type == :json && column.array_default
 
       required = column.rule != :update && required_column?(column)
       line = "#{required ? 'required' : 'optional'} #{column.name.to_sym.inspect}, :#{type}"
@@ -1095,6 +1099,41 @@ module Permittable
       notes.empty? ? line : "#{line} # #{notes.join('; ')}"
     end
 
+    # A PostgreSQL array column (`t.string :tags, array: true`) reports its
+    # ELEMENT type as `type` and says it is an array through `array?`. Drafted
+    # as a scalar, it would reject as invalid_type the very array it stores
+    # the moment the draft is enforced. `of:` takes only a scalar type, so a
+    # json/jsonb/hstore element type (an array of documents) is left as a
+    # TODO, as is any element type with no contract type at all.
+    def array_column_line(column)
+      type = COLUMN_TYPES[column.type]
+      unless type && type != :json
+        return "# TODO: #{column.name} (#{column.type}[]) has no contract type — declare it as a nested block or an array"
+      end
+
+      required = column.rule != :update && required_column?(column)
+      line = "array #{column.name.to_sym.inspect}, of: :#{type}#{', required: true' if required}"
+      notes = [column.default, *column_todos(column), "TODO: declare length: — an array without one is unbounded"]
+      "#{line} # #{notes.compact.join('; ')}"
+    end
+
+    # :json accepts only an object, but a json/jsonb column can as well hold
+    # an array — and when its default is one, it does: drafted as :json, it
+    # rejected as invalid_type, once enforced, what every client sends for
+    # it. Whether the elements are scalars or objects the column cannot say,
+    # so it is a TODO naming both declarations rather than a guess.
+    def json_array_todo(column)
+      name = column.name.to_sym.inspect
+      "# TODO: #{column.name} (#{column.type}) defaults to an array, which :json refuses — declare it " \
+        "`array #{name}, of: :string` (confirm the element type) or `array #{name} do ... end` for objects"
+    end
+
+    # A database default as the adapter reports it: the SQL literal "[]"
+    # through Rails 8.0, possibly the cast Array after.
+    def array_default?(default)
+      default.is_a?(Array) || (default.is_a?(String) && default.lstrip.start_with?("["))
+    end
+
     # Drafting from columns alone, a sensitive column is left out of the
     # fields — nothing says any client sends it — and named here instead.
     # The lock_version note says where to declare it in the rules actually

data/lib/permittable/json_schema.rb

@@ -391,16 +391,28 @@ module Permittable
     # length: reasons about characters on strings and element count on
     # arrays; either way it is an exact Integer or a Range (possibly endless
     # / beginless, possibly exclusive).
+    # An infinite end (`1..Float::INFINITY`) is no bound, as for numeric
+    # `in:` — and JSON has no Infinity, so exporting it raised.
     def length_bounds(spec)
       case spec
       when Integer then [spec, spec]
       when Range
-        max = spec.end && spec.exclude_end? ? spec.end - 1 : spec.end
-        [spec.begin, max]
+        min = finite_length(spec.begin)
+        max = finite_length(spec.end)
+        max -= 1 if max && spec.exclude_end?
+        [min, max]
       else [nil, nil]
       end
     end
 
+    # A whole-number Float/Rational end (`1..10.0`) is published as the
+    # Integer it means: minLength and friends are counts.
+    def finite_length(value)
+      return nil if value.nil? || (value.is_a?(Float) && value.infinite?)
+
+      value.to_i
+    end
+
     # Documentation keys shared by every field kind. `default:`/`example:`
     # are stored as the contract casts them (Date, Time, BigDecimal), so they
     # are re-encoded as JSON scalars.

data/lib/permittable/open_api.rb

@@ -373,7 +373,7 @@ module Permittable
         else
           free.each do |path, verb, template|
             holder = (paths[path] ||= {})
-            placed = with_path_parameters(operation, path)
+            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path)
             holder[verb] = template ? placed.merge("x-permittable-path" => template) : placed
             slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner, path)
           end
@@ -488,23 +488,93 @@ module Permittable
     # OpenAPI 3.1 requires every variable in a path template to be declared as
     # a path parameter — a document templating {id} without declaring it is
     # invalid, which every member route produced. The route set does not say
-    # what an :id is and the exporter does not guess: a path segment arrives as
-    # a string, so that is what it is documented as.
-    def with_path_parameters(operation, path)
-      variables = path.scan(/\{(\w+)\}/).flatten
+    # what an :id is, so a variable is a string unless the contract says
+    # otherwise: a rootless contract field named like one is that parameter's
+    # schema (path_fields), and leaves the body schema.
+    #
+    # `own` is the route's own spelling of the template, which differs
+    # from `path` when collapse_shapes placed the route under another
+    # route's spelling: the same shape, so the names pair up by position.
+    def with_path_parameters(operation, path, rule, own = path)
+      # A name the path templates twice (a mount and an engine route both
+      # name `:id`) is declared once: OpenAPI forbids two parameters with
+      # one name and location.
+      variables = path.scan(/\{(\w+)\}/).flatten.uniq
       return operation if variables.empty?
 
+      own_names = own.scan(/\{(\w+)\}/).flatten
+      fields = path_fields(rule, path.scan(/\{(\w+)\}/).flatten.zip(own_names).uniq(&:first))
       parameters = variables.map do |name|
-        { "name" => name, "in" => "path", "required" => true, "schema" => { "type" => "string" } }
+        schema = fields[name] ? path_schema(fields[name]) : { "type" => "string" }
+        { "name" => name, "in" => "path", "required" => true, "schema" => schema }
       end
       # Inserted ahead of requestBody, where a reader of the document expects
       # it; emission stays deterministic either way.
       operation.each_with_object({}) do |(key, value), out|
-        out["parameters"] = parameters if key == "requestBody"
-        out[key] = value
+        if key == "requestBody"
+          out["parameters"] = parameters
+          value = body_without(rule, fields.values, own_names)
+        end
+        out[key] = value unless value.nil?
       end
     end
 
+    # { path variable => the contract's field for it }. Rails merges the
+    # route's path parameters over the request's, so a field the route fills
+    # from the URL is read from the URL, never from the body: `id` in the
+    # body is overwritten, and a request that leaves it out is fine. A rooted
+    # contract reads its fields from inside the root, which a path parameter
+    # never reaches, so only a rootless one has such fields, and only at its
+    # top level. `names` pairs each variable of the placed path with the
+    # route's own name for it.
+    #
+    # Only a scalar field moves. A URL segment is one string, so an array or
+    # a hash can never be what it carries (`POST /defs/1,2` against
+    # `array :id` is a 422). Such a field stays in the body, where a client
+    # can at least say what it means.
+    def path_fields(rule, names)
+      return {} if rule[:root]
+
+      names.filter_map do |variable, own|
+        field = rule[:fields].find { |f| f[:name].to_s == own }
+        [variable, field] if field && field[:kind] == :scalar
+      end.to_h
+    end
+
+    # A moved field's schema as the path parameter documents it. The URL
+    # always supplies the segment, so a `default:` never applies and the
+    # value is never null: `nullable:` would only add "null" to the type.
+    def path_schema(field)
+      JsonSchema.field(field.except(:default, :nullable))
+    end
+
+    # The requestBody for `rule` without the fields a path parameter took
+    # over; nil, to leave it out, when that was every field. Such a body
+    # would be an empty object. An action declared with no fields at all
+    # keeps the empty body it always had.
+    #
+    # `unknown: :error` forbids every key the contract does not declare, but
+    # the runtime exempts the route's path parameters from that check and
+    # then overwrites them with the URL's values: `PATCH /widgets/7` with
+    # {"id":7,"name":"x"} is a 200 whether or not the contract declares `id`.
+    # That is the payload a Rails form, or a client sending a record back,
+    # produces, so the schema must not forbid it. Each name the route
+    # templates therefore stays in the body as an unconstrained property,
+    # any value and never required, since the value is read from the URL and
+    # nothing in the body can make the request wrong. A rooted contract
+    # needs none of this: its wrapper object is permissive already.
+    def body_without(rule, moved, templated)
+      rest = rule[:fields] - moved
+      return if rest.empty? && !moved.empty?
+
+      body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest))
+      return body unless rule[:unknown] == :error && !rule[:root]
+
+      properties = body["content"]["application/json"]["schema"]["properties"]
+      templated.each { |name| properties[name] ||= {} }
+      body
+    end
+
     # Drops every descriptor for a verb and concrete path that an earlier,
     # unconstrained route already answers (rails_routes calls it last).
     # Journey sorts the routes matching a request by precedence, their
@@ -533,10 +603,13 @@ module Permittable
     #
     # Descriptors arrive in route order (then verb, then optional variant),
     # so the first one seen is the first route. Precedence is a property of
-    # ONE route set, which is why this runs inside each rails_routes call and
-    # not in the readers: an engine's routes are relative to its mount point,
-    # and a list concatenated from an app's and an engine's must not let one
-    # shadow the other.
+    # ONE route table, which is why this runs once inside each rails_routes
+    # call and not in the readers: a list concatenated from an app's and an
+    # engine's must not let one shadow the other. An engine followed from its
+    # mount is part of that one table, expanded where the mount is drawn, so
+    # an app route ahead of the mount hides the engine's route for the same
+    # slot and an engine route hides a later app one (see rails_routes). An
+    # engine route is unconditional only when its mount is as well.
     #
     # Two more limits, both towards listing more. Only identical templates
     # are compared, so templates that differ at all, even only in a
@@ -616,9 +689,77 @@ module Permittable
     # A verb on a path that an earlier, unconstrained route already answers
     # is left out: Rails never dispatches it to the later route (see
     # drop_shadowed).
-    def rails_routes(app)
-      descriptors = app.routes.routes.each_with_index.flat_map do |route, index|
+    #
+    # A mounted Rails engine is part of the application: `mount Billing::Engine
+    # => "/billing"` makes every route the engine draws a URL of the app, so
+    # the audit's gate and the export must see them. With `engines: true`
+    # (the default) each such mount is followed into the engine's own route
+    # set, and the mount's path is put in front of every path found there,
+    # token by token, so a mount under `scope "(:locale)"`, one at a
+    # dynamic `at: ":tenant"` and one at "/" expand and join exactly as an
+    # app route would. A route reached through a mount carries its position
+    # as an Array, `[mount, route]` (`[3, 0, 5]` through an engine mounted in
+    # an engine), where an app route carries a bare Integer; so one engine
+    # mounted twice is two routes to its actions, as it is to a client. Only
+    # a Rails engine is followed: a Sidekiq::Web or a proc has no route set
+    # of ours to read and is skipped, as it always was. `engines: false`
+    # reads the one route set alone, for a caller that concatenates the lists
+    # of an app and its engines itself.
+    #
+    # Rails tries the routes in order with a mount standing where it is
+    # drawn, so the engine's routes are judged in that one order with the
+    # app's (see drop_shadowed): an app route ahead of the mount answers
+    # before the engine is asked, an engine route that matches answers and
+    # leaves an app route behind the mount unreached, and only a request the
+    # engine has no route for goes on (X-Cascade). A mount's `via:` limits
+    # the verbs it hands over: another verb is passed on, never answered by
+    # the engine.
+    #
+    # A parameter the mount and an engine route both name (`/{id}/.../{id}`)
+    # is not renamed: the template names it twice, the operation declares it
+    # once, and the README says so.
+    def rails_routes(app, engines: true)
+      drop_shadowed(collect_routes(app.routes, engines: engines, prefixes: [Prefix.new([], [])], parents: [],
+                                               visiting: [].freeze, reachable: true))
+    end
+
+    # What a route set mounted at one variant of its mount's path is led by.
+    # `tokens` are the mount's path from the root (see join_paths).
+    # `shadowed_by` are the paths of the variants Rails tries first, which
+    # leave this one nothing that they accept: a mount at "/" under
+    # `scope "(:locale)"` is matched as `/{locale}` before it is matched as
+    # "/", so /posts is the locale "posts" asking for the engine's root, and
+    # the engine's own /posts is not reached through the second variant. The
+    # mount's path is matched as a whole, unanchored and with no way back
+    # into it once the engine has been asked, so a variant that fits the
+    # leading segments of a path takes it whether or not the engine has a
+    # route for the rest.
+    Prefix = Struct.new(:tokens, :shadowed_by)
+
+    # The descriptors of one route set (`set`, anything with `routes`), each
+    # path led by every one of `prefixes` (a Prefix for each variant of the
+    # mounts above it, one empty one at the top) and each `route:` led by
+    # `parents`. `reachable` is whether every mount above answers every
+    # request for its path (see unconditional?); a route behind one that
+    # does not may be passed over, so it hides nothing. `visiting` is the
+    # route sets above this one, so an engine that mounts itself, or an app
+    # and engine that mount each other, ends the walk instead of recursing
+    # for good. Rails would loop on such a request too; the audit must not
+    # hang on it.
+    #
+    # The descriptors still carry `unconditional:`; the caller runs
+    # drop_shadowed over the whole list, mounts expanded in place.
+    def collect_routes(set, engines:, prefixes:, parents:, visiting:, reachable:)
+      visiting += [set]
+      set.routes.each_with_index.flat_map do |route, index|
+        id = parents.empty? ? index : parents + [index]
         requirements = route.requirements
+        if engines && (mounted = mounted_routes(route)) && visiting.none? { |above| above.equal?(mounted) }
+          found = collect_routes(mounted, engines: engines, prefixes: mount_prefixes(prefixes, route), parents: Array(id),
+                                          visiting: visiting, reachable: reachable && unconditional?(route))
+          verbs = route.verb.to_s.downcase.split("|")
+          next verbs.empty? ? found : found.select { |descriptor| verbs.include?(descriptor[:verb]) }
+        end
         verb = route.verb.to_s
         next [] if requirements[:controller].nil? || requirements[:action].nil?
 
@@ -627,9 +768,9 @@ module Permittable
         # audit entirely. Expand it into the verbs it actually answers.
         verb = ALL_VERBS if verb.empty?
 
-        variants = optional_variants(route.path.spec, requirements)
+        variants = optional_variants(route.path.spec, requirements, prefixes)
         # Read once per route; drop_shadowed reads it, then strips it.
-        unconditional = unconditional?(route)
+        unconditional = reachable && unconditional?(route)
         # One route can answer several verbs (`match via: [:patch, :put]`, and
         # the PATCH|PUT pair resources generates); documenting only the first
         # dropped the others from the export entirely. Verb by verb, then
@@ -638,12 +779,47 @@ module Permittable
         verb.split("|").flat_map do |single|
           variants.map do |path, shadows|
             descriptor = { controller: requirements[:controller], action: requirements[:action],
-                           verb: single.downcase, path: path, route: index, unconditional: unconditional }
+                           verb: single.downcase, path: path, route: id, unconditional: unconditional }
             shadows.empty? ? descriptor : descriptor.merge(shadows: shadows)
           end
         end
       end
-      drop_shadowed(descriptors)
+    end
+
+    # The Prefix of each variant of a mount's path under each of `prefixes`,
+    # outermost mount first, and within a mount present before absent, which
+    # is the order Rails' regexp tries them in. A variant is shadowed by every
+    # variant ahead of it: those of the same mount, and (through the
+    # `shadowed_by` it inherits) those of a mount above, judged where each
+    # was matched.
+    def mount_prefixes(prefixes, route)
+      own = variant_tokens(route.path.spec, route.requirements)
+      prefixes.flat_map do |above|
+        own.each_with_index.map do |tokens, index|
+          Prefix.new(join_paths(above.tokens, tokens),
+                     above.shadowed_by + own.take(index).map { |earlier| join_paths(above.tokens, earlier) })
+        end
+      end
+    end
+
+    # The route set a mount route hands requests to, or nil for any other
+    # route. Rails itself asks `route.app.engine?` (RoutesInspector does)
+    # and reads the set off `rack_app`. A route that cannot answer, such as a
+    # hand-built duck, is not a mount.
+    def mounted_routes(route)
+      return unless route.respond_to?(:app) && route.app.respond_to?(:engine?) && route.app.engine?
+
+      engine = route.app.rack_app
+      engine.routes if engine.respond_to?(:routes)
+    end
+
+    # `outer` then `inner`, as one path: the slash the mount ends in and the
+    # one the inner path starts with are one slash, and a route to the
+    # engine's root ("/") adds nothing to the mount's own path.
+    def join_paths(outer, inner)
+      inner = inner.drop(1) if outer.last == "/" && inner.first == "/"
+      inner = [] if inner == ["/"] && !outer.empty?
+      join_literals(outer + inner)
     end
 
     # A route parameter as optional_variants reads it: a `:name` segment or a
@@ -704,13 +880,23 @@ module Permittable
     # string: `to_s` prints an escaped parenthesis in a literal as a bare
     # one, which a string scan then read as a group. A Journey-shaped stand-in
     # may carry a String spec instead (string_variants).
-    def optional_variants(spec, requirements = {})
-      variants = if spec.respond_to?(:type)
-                   tree_variants(spec, requirements)
-                 else
-                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
-                 end
-      variants = variants.map { |tokens| join_literals(tokens) }
+    #
+    # `prefixes` are the Prefix of each variant of the mounts the route sits
+    # under (one empty one, none, by default). Each is put in front of every
+    # variant, the mount's variants outermost, which is the order Rails'
+    # regexp tries them in; a path a mount variant ahead of its own takes
+    # first is left out (see Prefix), and the shadowing above then judges the
+    # rest.
+    def optional_variants(spec, requirements = {}, prefixes = [Prefix.new([], [])])
+      # The route's own variants are judged before a mount's path is put in
+      # front of them: an empty one (`(:locale(/:region))` with nothing
+      # present) is no request path, but joined onto a mount it would read as
+      # the mount's own path, which Rails does not hand to that route.
+      own = variant_tokens(spec, requirements).select { |tokens| request_path?(tokens) }
+      variants = prefixes.flat_map do |prefix|
+        own.map { |tokens| join_paths(prefix.tokens, tokens) }
+           .reject { |joined| prefix.shadowed_by.any? { |earlier| shadowed?(earlier, joined.first(earlier.length)) } }
+      end
       # No group, no choice: nothing for one variant to shadow.
       return { render(variants.first) => [] } if variants.one?
 
@@ -732,6 +918,17 @@ module Permittable
       kept.to_a.reverse.to_h
     end
 
+    # The variants of a path spec, each a list of tokens with adjacent text
+    # joined (see join_literals), before any is dropped as shadowed.
+    def variant_tokens(spec, requirements)
+      variants = if spec.respond_to?(:type)
+                   tree_variants(spec, requirements)
+                 else
+                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
+                 end
+      variants.map { |tokens| join_literals(tokens) }
+    end
+
     # A Journey tree's variants, each a list of tokens: literal text and
     # Param. A group yields its contents' variants, then the empty one —
     # present before absent, as Rails' regexp tries them — except the