permittable 0.11.0 → 0.12.0

data/lib/permittable/generator.rb

@@ -32,12 +32,18 @@ module Permittable
     # Building these once in columns_for keeps every drafting path (columns
     # alone, or a scan typed from columns) reading the same answers.
     #
+    # `assigned` marks a column the database or Rails fills in (a generated
+    # primary key, a timestamp): drafted from the columns alone it is left
+    # out, and a permit call that lists it gets it typed from the schema, but
+    # never `required`, since no client has to send it. A primary key the
+    # client must send (a natural key) is not assigned (see assigned?).
+    #
     # `rule` and `listed` are how column_line is told what it is drafting
     # for: the rule (see render) and whether the controller's permit call
     # 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, 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
@@ -86,11 +92,29 @@ module Permittable
       end
     end
 
-    # One permit call, with an optional leading `.require(:root)`. The args
-    # capture tolerates brackets and newlines but not parentheses — a call
-    # whose arguments contain a method call is skipped entirely rather than
-    # half-read.
-    PERMIT_CALL = /params\s*(?:\.\s*require\(\s*:(\w+)\s*\))?\s*\.\s*permit\(([^()]*)\)/m
+    # `params` itself, not the tail of another name: `user_params.permit(...)`
+    # is called on a helper's result (`params.require(:user)`, say), whose
+    # root a rootless read of it would drop. `@params` and `$params` are
+    # variables, except `@_params`, the one Rails itself keeps the controller's
+    # params in. A `.` before it is fine: `self.params.permit(...)` is the
+    # real thing.
+    PARAMS = /(?<![\w@$])(?:@_)?params/
+
+    # One permit call, with an optional leading `.require(:root)` — the root
+    # spelled `:user`, `"user"` or `'user'` (groups 1-3; a String root's
+    # content is masked, so it is read back by offset like any argument).
+    # The args capture (group 4) tolerates brackets and newlines but not
+    # parentheses — a call whose arguments contain a method call is skipped
+    # entirely rather than half-read. Without parentheses (`permit :name,
+    # :email`, common in older controllers) group 4 is empty and the
+    # arguments run to the end of the statement: see call_args.
+    PERMIT_CALL = /#{PARAMS}\s*(?:\.\s*require\(\s*(?::(\w+)|"([^"\n]*)"|'([^'\n]*)')\s*\))?\s*\.\s*
+                   permit(?:\(([^()]*)\)|[ \t]+(?=[^\s(]))/mx
+
+    # A trailing `if`/`unless`/`rescue` modifier on a paren-less call, which
+    # is not one of its arguments.
+    # At the start too: `permit if admin?` has no arguments at all.
+    BARE_MODIFIER = /(?:\A|\s+)(?:if|unless|rescue)\s.*\z/m
 
     # One Rails 8 `params.expect` call — the replacement for
     # `require(...).permit(...)`, and the reason this scanner exists twice: a
@@ -100,21 +124,40 @@ module Permittable
     # PERMIT_CALL: brackets and newlines are fine, a parenthesis means a
     # method call in the arguments and the whole call is skipped rather than
     # half-read.
-    EXPECT_CALL = /params\s*\.\s*expect\(([^()]*)\)/m
+    EXPECT_CALL = /#{PARAMS}\s*\.\s*expect(?:\(([^()]*)\)|[ \t]+(?=[^\s(]))/m
 
     # The required root envelope of an expect call: `user: [...]`, where the
-    # brackets hold fields — not the empty `tag_names: []` of an
-    # array-of-scalars root, and not the `comments: [[...]]` of an
-    # array-of-hashes root, neither of which a rooted contract can express.
-    # The lookahead skips whitespace itself: `\[\s*(?!...)` let `\s*` match
-    # nothing and waved the spaced `tag_names: [ ]` through as an envelope
-    # with no fields.
-    EXPECT_ENVELOPE = /\A(\w+):\s*\[(?!\s*[\[\]])\s*(.*?)\s*\]\z/m
-
-    # An envelope whose fields live in a constant: `post: PERMITTED_PARAMS`.
-    # The fields cannot be read, but the root can, and read as a rootless
-    # argument it let a `params.permit(:page)` beside it take the root.
-    EXPECT_CONSTANT_ENVELOPE = /\A(\w+):\s*((?:::)?[A-Z]\w*(?:::[A-Z]\w*)*)\z/
+    # brackets hold fields. Which brackets hold fields is `envelope`'s call,
+    # not this pattern's: not the empty `tag_names: []` of an array-of-scalars
+    # root, and not the `comments: [[...]]` of an array-of-hashes root,
+    # neither of which a rooted contract can express. Rails reads `[[...]]` as
+    # an array of hashes only when the outer list holds that one element;
+    # `[[:name, :email], :age]` is the flat list `[:name, :email, :age]`.
+    EXPECT_ENVELOPE = /\A(\w+):\s*\[(.*)\]\z/m
+
+    # An envelope whose fields cannot be read: they live in a constant
+    # (`post: PERMITTED_PARAMS`) or a local (`post: permitted_keys`), or a
+    # word list holds a key that is not a plain one (`post: %i[first-name]`).
+    # Rails requires `post` whatever its value holds, so the root can still
+    # be read; read as a rootless argument it let a `params.permit(:page)`
+    # beside it take the root, and dropped the root when it stood alone. A
+    # value that opens with `[` is an array: EXPECT_ENVELOPE's fields, or a
+    # root a rooted contract cannot express (see there), never this.
+    EXPECT_OPAQUE_ENVELOPE = /\A(\w+):\s*([^\[\s].*)\z/m
+
+    # A %i/%w word list, or %I/%W: RuboCop's default Style/SymbolArray and
+    # Style/WordArray rewrite `[:name, :email]` into `%i[name email]`, and
+    # Rails reads the two alike. Delimited by `[]`, `{}`, `<>`, or the same
+    # punctuation at both ends — not `()`, as a parenthesis already makes the
+    # whole call unreadable (see PERMIT_CALL). The words are the text between
+    # the delimiters, whichever alternative matched.
+    WORD_LIST = /%[iIwW](?:\[[^\[\]]*\]|\{[^{}]*\}|<[^<>]*>|([^\w\s(),\[\]{}<>])(?:(?!\1).)*\1)/m
+
+    # A list among the filters, splatted or not: `[:name, :email]`, or a word
+    # list once bracket_word_lists has spelled it so. Rails flattens the
+    # filters it is given, so its elements are filters in their own right.
+    # Only a flat one: a list holding a list is left whole, unparsed.
+    LIST_ARG = /\A(?:\*\s*)?\[([^\[\]]*)\]\z/
 
     # The key of a single-key rootless EXPECT lookup that is a route param,
     # not input: the Rails 8 scaffold's `Post.find(params.expect(:id))`, or a
@@ -222,11 +265,19 @@ module Permittable
     # The lexed tokens shared by executable_source and masked_source, with
     # comments already dropped — nil when Ripper could not lex `source` at
     # all, or found nothing.
+    # A comment token carries its line's newline ("# note\n"), so dropping
+    # it whole joined that line to the next. A parenthesised call never
+    # noticed; a paren-less one ends at its line (see bare_args_end), so the
+    # newline is kept.
     def code_tokens(source)
       tokens = Ripper.lex(source)
       return nil if tokens.nil? || tokens.empty?
 
-      tokens.reject { |token| COMMENT_TOKENS.include?(token[1]) }
+      tokens.filter_map do |token|
+        next token unless COMMENT_TOKENS.include?(token[1])
+
+        [token[0], :on_nl, "\n", token[3]] if token[2].end_with?("\n")
+      end
     end
 
     # Merge every `params.permit` and `params.expect` call found in the
@@ -261,8 +312,11 @@ module Permittable
       raw = source.to_s
       source = executable_source(raw)
       masked = masked_source(raw)
-      permits = matches(masked, PERMIT_CALL).map { |match| permit_call(source, match) }
-      expects = matches(masked, EXPECT_CALL).map { |match| expect_calls(match.begin(0), split_args(group(source, match, 1))) }
+      permits = matches(masked, PERMIT_CALL).filter_map { |match| permit_call(source, masked, match) }
+      expects = matches(masked, EXPECT_CALL).filter_map do |match|
+        args, = call_args(source, masked, match, 1)
+        expect_calls(match.begin(0), split_args(args)) if args
+      end
       result.calls = permits.size + expects.size
       calls = (permits + expects).flatten.sort_by.with_index { |call, index| [call.position, index] }
       result.root = choose_root(calls, model&.name && default_root(model), exclude)
@@ -321,18 +375,53 @@ module Permittable
     # ActiveStorage's direct uploads controller is the case this exists for —
     # it was drafted, and a contract pasted into a gem's controller is not
     # one the app can keep. A "controller#action" entry takes only that
-    # action out of the draft, and a controller with no drafted action left
-    # is skipped. Naming a controller to the task drafts it regardless, the
-    # way it drafts a covered one.
+    # action out of the draft, and so does an action the controller does not
+    # define (see undefined_actions): a SessionsController with only `create`
+    # and `destroy` gets no `:update` rule, and ApplicationController, which
+    # defines neither, would otherwise hand its rule to every controller
+    # below it. A controller with no drafted action left is skipped. Naming a
+    # controller to the task drafts it regardless (see named_target), the way
+    # it drafts a covered one.
     def targets(controllers, ignore: Permittable.audit_ignore, root: Audit.app_root)
       controllers.each_with_object({}) do |controller, found|
         next if controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
 
-        skipped = DEFAULT_ACTIONS.select { |action| Audit.ignore_reason(controller, action, ignore: ignore, root: root) }
+        undefined = undefined_actions(controller)
+        skipped = DEFAULT_ACTIONS.select do |action|
+          Audit.ignore_reason(controller, action, ignore: ignore, root: root) || undefined.include?(action)
+        end
         found[controller] = skipped unless skipped == DEFAULT_ACTIONS
       end
     end
 
+    # What to leave out of the draft of a controller named to the task: the
+    # drafted actions it does not define, as in the sweep — unless it defines
+    # none of them. Then the name is all there is to go on, and it is drafted
+    # whole, as it always was.
+    def named_target(controller)
+      undefined = undefined_actions(controller)
+      undefined == DEFAULT_ACTIONS ? [] : undefined
+    end
+
+    # The drafted actions `controller` does not define, by the audit's own
+    # reading of it (Audit.missing_lookup): not just its action_methods, since
+    # an `action_missing` handler or a template answers an action with no
+    # method, and a controller that cannot list its actions is assumed to
+    # define them all. A second definition here would drift from what
+    # permittable:audit then calls stale.
+    #
+    # Reading it can build the controller (see Audit.dispatchable?), which
+    # rescues only a StandardError. A controller whose `initialize` raises a
+    # ScriptError, such as NotImplementedError, would abort the whole sweep,
+    # which never built a controller before. It is inconclusive, so it is
+    # assumed to define both, the same answer as one that cannot list them.
+    def undefined_actions(controller)
+      missing = Audit.missing_lookup(controller)
+      DEFAULT_ACTIONS.select { |action| missing[action.to_s] }
+    rescue StandardError, ScriptError
+      []
+    end
+
     # The core: knowledge in (columns and/or a scan), snippet out. Returns a
     # String of valid Ruby, or nil when neither source of knowledge exists —
     # or when neither can declare a single field, since a contract of only
@@ -342,16 +431,22 @@ module Permittable
       columns = columns_for(model)
       scan = nil unless scan&.found?
       return nil unless columns || scan
-      return column_draft(model, columns.values, [], except: except) unless scan
+      return column_draft(model, unassigned(columns), [], except: except) unless scan
 
-      shared = scanned_lines(scan, listed_columns(columns, :shared))
+      shared = scanned_lines(scan, listed_columns(columns, :shared), model: model)
       return fallback_draft(model, scan, columns, except: except) unless declares_field?(shared)
 
       render(root: scan.root, model: columns && model, except: except) do |rule|
-        scanned_lines(scan, listed_columns(columns, rule))
+        scanned_lines(scan, listed_columns(columns, rule), model: model)
       end
     end
 
+    # The columns worth drafting without a permit call to name them: not the
+    # ones the database or Rails assigns (see DraftColumn).
+    def unassigned(columns)
+      columns.values.reject(&:assigned)
+    end
+
     # The columns as one rule drafts them (see DraftColumn#in_rule), each
     # marked listed: on the scan path a column is drafted only because the
     # controller's own calls name it.
@@ -387,7 +482,7 @@ module Permittable
 
       root = scan.root || (rootless_body?(scan) ? nil : default_root(model))
       undrafted = (Array(scan.undecided) + Array(scan.route_params).filter_map { |arg| scalar_key(arg) }).map(&:to_s)
-      drafted = columns.except(*undrafted)
+      drafted = columns.reject { |_, column| column.assigned }.except(*undrafted)
       # As in drop_drafted_todos: a rootless key the columns now declare is
       # not also a "not in this contract" TODO.
       scan = scan.dup.tap { |copy| copy.rootless = Array(scan.rootless).reject { |arg| drafted.key?(scalar_key(arg).to_s) } }
@@ -416,9 +511,13 @@ module Permittable
       model.respond_to?(:columns) ? model : nil
     end
 
-    # The columns a contract should cover, keyed by name — or nil when there
-    # is no model or its schema is unreachable (same philosophy as the drift
-    # guard: never let generation crash on a half-migrated database).
+    # Every column, keyed by name — or nil when there is no model or its
+    # schema is unreachable (same philosophy as the drift guard: never let
+    # generation crash on a half-migrated database). All of them, the
+    # primary key and timestamps too: this is also where a permitted key's
+    # type is looked up, and a column left out here read as "not a
+    # database column". What is drafted without a permit call is narrowed
+    # later (see DraftColumn#assigned).
     def columns_for(model)
       columns = schema_columns(model)
       columns&.to_h { |column| [column.name, draft_column(model, column)] }
@@ -441,10 +540,7 @@ module Permittable
       return nil unless model.respond_to?(:columns)
       return nil unless model.table_exists?
 
-      # Array() flattens a composite primary key (an Array in Rails 7.1+)
-      # into its column names; a nil primary key becomes [].
-      skipped = SKIPPED_COLUMNS + Array(model.primary_key).map(&:to_s)
-      model.columns.reject { |c| skipped.include?(c.name) }
+      model.columns
     rescue StandardError => e
       raise unless defined?(ActiveRecord::ActiveRecordError) && e.is_a?(ActiveRecord::ActiveRecordError)
 
@@ -458,7 +554,40 @@ 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,
-                      sensitive: sensitive_role(model, column.name), **model_facts(model, column))
+                      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
+
+    # Whether the database or Rails fills the column in, so no client has to
+    # send it. A timestamp is; a primary key only when the database really
+    # generates it: an auto-increment column (the adapter says so, wherever
+    # it sits in the key: MySQL allows `PRIMARY KEY (region, id)` with `id
+    # AUTO_INCREMENT`), or a key with a default or a default function (a
+    # uuid). An adapter without that flag falls back to the integer of a
+    # single-column key. A natural key (`sku`, a `create_table ..., id:
+    # :string`) or a part of a composite key with no such flag is the
+    # client's to send, and is drafted like any other column.
+    # Array() flattens a composite primary key (an Array in Rails 7.1+) into
+    # its column names; a nil primary key becomes [].
+    def assigned?(model, column)
+      return true if SKIPPED_COLUMNS.include?(column.name)
+
+      keys = Array(model.primary_key).map(&:to_s)
+      return false unless keys.include?(column.name)
+
+      auto_increment?(column, sole_key: keys.one?) || !column.default.nil? || default_function?(column)
+    end
+
+    def auto_increment?(column, sole_key:)
+      return column.auto_increment? if column.respond_to?(:auto_increment?)
+
+      sole_key && column.type == :integer
+    end
+
+    def default_function?(column)
+      column.respond_to?(:default_function) && !column.default_function.nil?
     end
 
     # What the model adds to one column. An error reading it degrades THAT
@@ -592,20 +721,43 @@ module Permittable
     # -- scan parsing -------------------------------------------------------
 
     # Split a permit argument list on top-level commas only, so `address:
-    # [:city, :zip]` stays one argument.
+    # [:city, :zip]` stays one argument. A list argument is replaced by its
+    # elements (see LIST_ARG).
     def split_args(args)
+      split_top_level(args).flat_map do |part|
+        list = LIST_ARG.match(bracket_word_lists(part))
+        list ? split_args(list[1]) : [part]
+      end
+    end
+
+    # The top-level, comma-separated parts of `args`, as written. A word list
+    # delimited by commas (`%w,name email,`) is kept whole, so it stays one
+    # unreadable argument rather than the TODOs of its pieces (see WORD_LIST).
+    def split_top_level(args)
       parts = [+""]
       depth = 0
-      args.each_char do |char|
-        depth += 1 if "[{".include?(char)
-        depth -= 1 if "]}".include?(char)
-        next parts << +"" if char == "," && depth.zero?
+      args.scan(/%[iIwW],[^,]*,|./m) do |token|
+        depth += 1 if token.size == 1 && "[{".include?(token)
+        depth -= 1 if token.size == 1 && "]}".include?(token)
+        next parts << +"" if token == "," && depth.zero?
 
-        parts.last << char
+        parts.last << token
       end
       parts.map(&:strip).reject(&:empty?)
     end
 
+    # `text` with each word list of plain keys spelled as the list it equals:
+    # `%i[name email]` as `[:name, :email]`, `%w[]` as `[]`, so the shapes
+    # above read it. A word list holding any other word — quoted, escaped or
+    # interpolated — is left as written, and stays unparsed. Only for
+    # matching: a TODO quotes the argument as the source spells it.
+    def bracket_word_lists(text)
+      text.gsub(WORD_LIST) do |list|
+        words = list[3...-1].split
+        words.all? { |word| word.match?(/\A\w+\z/) } ? "[#{words.map { |word| ":#{word}" }.join(', ')}]" : list
+      end
+    end
+
     # An expect call's arguments, as one Call per envelope. The bracketed
     # arguments are required root envelopes and their contents are fields.
     # Plain symbols are fields only when there is no envelope
@@ -625,12 +777,26 @@ module Permittable
     end
 
     # An expect argument as `[root, fields]` when it is an envelope, else nil.
-    # A constant envelope's one "field" is the constant, kept as unparsable.
+    # An opaque envelope's one "field" is its value, kept as unparsable.
+    #
+    # The shape is judged with word lists bracketed: `user: %i[name email]`
+    # is the envelope `user: [:name, :email]`, and `items: [%i[sku]]` the
+    # array-of-hashes root `items: [[:sku]]`. It is judged on the elements
+    # the outer list holds, as Rails does, not on the flattened fields: the
+    # list is an array of hashes (or empty) only when it holds nothing but one
+    # list, so `user: [%i[name email], :age]` is still the `user` envelope
+    # with three fields. A bracketed envelope's fields are split as the source
+    # spells them, so a TODO for one quotes it as written.
     def envelope(arg)
-      if (match = EXPECT_ENVELOPE.match(arg))
-        [match[1].to_sym, split_args(match[2])]
-      elsif (match = EXPECT_CONSTANT_ENVELOPE.match(arg))
-        [match[1].to_sym, [match[2]]]
+      listed = bracket_word_lists(arg)
+      if (match = EXPECT_ENVELOPE.match(listed))
+        elements = split_top_level(match[2])
+        return if elements.empty? || (elements.one? && elements.first.start_with?("["))
+
+        written = EXPECT_ENVELOPE.match(arg) || match
+        [match[1].to_sym, split_args(written[2])]
+      elsif (match = EXPECT_OPAQUE_ENVELOPE.match(listed))
+        [match[1].to_sym, [arg.sub(/\A\w+:\s*/, "")]]
       end
     end
 
@@ -640,13 +806,59 @@ module Permittable
     # own text may hold placeholders rather than a real string argument's
     # characters (see masked_source), so every group is read back out of
     # `source` by position instead of off `match` directly.
-    def permit_call(source, match)
-      args = split_args(group(source, match, 2))
-      root = group(source, match, 1)
-      return Call.new(match.begin(0), nil, args, []) unless root
+    # nil when the call cannot be read: a paren-less one whose arguments
+    # hold a method call, or a String root that is not a plain key.
+    def permit_call(source, masked, match)
+      args, finish = call_args(source, masked, match, 4)
+      return nil unless args
+
+      root = [1, 2, 3].filter_map { |index| group(source, match, index) }.first
+      return Call.new(match.begin(0), nil, split_args(args), []) unless root
+      return nil unless root.match?(/\A\w+\z/)
+
+      spelling = unparsed_arg(source[match.begin(0)...finish]).gsub(/\(\s+/, "(").gsub(/\s+\)/, ")")
+      Call.new(match.begin(0), root.to_sym, split_args(args), [], spelling)
+    end
+
+    # A call's argument text and where the call ends, or nil when it cannot
+    # be read. Parenthesised, that is the paren group. Without parentheses
+    # it runs from the match to the end of the statement (bare_args_end),
+    # less any trailing modifier.
+    def call_args(source, masked, match, paren_group)
+      return [group(source, match, paren_group), match.end(0)] if match.begin(paren_group)
+
+      finish = bare_args_end(masked, match.end(0))
+      return nil unless finish
+
+      # The call ends where its arguments do, so a TODO quoting it never
+      # quotes the modifier.
+      args = source[match.end(0)...finish].sub(BARE_MODIFIER, "").rstrip
+      args.empty? ? nil : [args, match.end(0) + args.length]
+    end
+
+    # Where a paren-less argument list ends: the first newline (or `;`)
+    # outside brackets that does not follow a `,` or a `\` — Ruby's own rule
+    # for continuing a command call onto the next line. A parenthesis means
+    # a method call in the arguments, and the call is skipped as the
+    # parenthesised form skips one; so are unbalanced brackets. Read on the
+    # masked source, where string content cannot open a bracket.
+    def bare_args_end(text, start)
+      depth = 0
+      last = nil
+      index = start
+      while index < text.length
+        char = text[index]
+        return nil if "()".include?(char)
 
-      spelling = unparsed_arg(group(source, match, 0)).gsub(/\(\s+/, "(").gsub(/\s+\)/, ")")
-      Call.new(match.begin(0), root.to_sym, args, [], spelling)
+        depth += 1 if "[{".include?(char)
+        depth -= 1 if "]}".include?(char)
+        return nil if depth.negative?
+        break if depth.zero? && (char == ";" || (char == "\n" && !(last && ",\\".include?(last))))
+
+        last = char unless char.match?(/\s/)
+        index += 1
+      end
+      depth.zero? ? index : nil
     end
 
     # A rootless expect call — or, when its one key is a route param
@@ -809,8 +1021,10 @@ module Permittable
 
     # One permit argument as `[shape, key]`, or `[shape, key, sub_keys]` for
     # the two hash shapes — nil when the conservative parser cannot read it,
-    # including a nested list with any sub-key it cannot read.
+    # including a nested list with any sub-key it cannot read. A word list
+    # reads as the list it equals: `address: %i[city zip]` is a nested hash.
     def parse_arg(arg)
+      arg = bracket_word_lists(arg)
       if (key = scalar_key(arg))
         [:scalars, key]
       elsif (match = ARRAY_ARG.match(arg))
@@ -872,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}"
@@ -883,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
@@ -924,9 +1175,15 @@ module Permittable
     # it back to its key. Left as a TODO rather than drafted: forms, the
     # common client, send the key. Only for an enum that stores Integers — a
     # string-backed one has no second spelling to admit.
+    #
+    # The transform is spelled out because the obvious one is wrong: with
+    # `key(v.to_i) || v`, "shipped".to_i is 0, so a NAME became the first
+    # key. Integer(v, exception: false) is nil for a name, which key() maps
+    # to nil. The type guard accepts this in: only beside a transform:.
     def enum_todo(column)
       "TODO: Rails also assigns the stored integers (#{column.name}: 1) — if API clients send them, add " \
-        "#{column.enum}.values.map(&:to_s) to in: and map them back to keys with transform:"
+        "#{column.enum}.values.map(&:to_s) to in: and map them back to keys with " \
+        "transform: ->(v) { #{column.enum}.key(Integer(v, exception: false)) || v }"
     end
 
     def unread_todo(column)
@@ -940,7 +1197,7 @@ module Permittable
     # request that omits the field, which would overwrite columns on partial
     # updates; the database already handles creation.
     def required_column?(column)
-      return false if column.null
+      return false if column.null || column.assigned
       return false unless column.default.nil?
 
       !column.default_function
@@ -949,13 +1206,13 @@ module Permittable
     # Scanned names are emitted with Symbol#inspect, not as `:#{name}`: a
     # string-keyed `permit("2fa")` scans to a name that is not a bare symbol
     # literal, and `:2fa` would make the whole draft a SyntaxError.
-    def scanned_lines(scan, columns)
+    def scanned_lines(scan, columns, model: nil)
       lines = scan.scalars.map { |name| scanned_scalar_line(name, columns) }
       lines += scan.arrays.map do |name|
         "array #{name.to_sym.inspect}, of: :string " \
           "# TODO: confirm the element type, and declare length: — an array without one is unbounded"
       end
-      scan.nested.each { |name, keys| lines += nested_lines(name, keys) }
+      scan.nested.each { |name, keys| lines += nested_lines(name, keys, model: model) }
       scan.nested_arrays.each { |name, keys| lines += nested_array_lines(name, keys) }
       lines + scan_todo_lines(scan)
     end
@@ -994,13 +1251,28 @@ module Permittable
       "#{field} # TODO: confirm the type"
     end
 
-    def nested_lines(name, keys)
+    # `permit(addresses_attributes: [...])` cannot say whether it permits one
+    # hash or many; the model can. When the key is a collection's nested
+    # attributes (has_many + accepts_nested_attributes_for), fields_for
+    # sends its records as `{"0" => {...}, "1" => {...}}`, which a nested
+    # block reads as unknown keys and silently drops, and an `array ... do`
+    # field reads as the records it encodes. A has_one's stay a nested block.
+    def nested_lines(name, keys, model: nil)
+      return nested_array_lines(name, keys) if collection_attributes?(model, name)
+
       ["optional #{name.to_sym.inspect} do # TODO: drafted from `#{name}: [...]` — " \
        "if this is an array of hashes, use `array #{name.to_sym.inspect} do`"] +
         sub_field_lines(keys) +
         ["end"]
     end
 
+    def collection_attributes?(model, name)
+      base = name.to_s.delete_suffix("_attributes")
+      return false if base == name.to_s || !model.respond_to?(:reflect_on_association)
+
+      model.reflect_on_association(base.to_sym)&.collection? || false
+    end
+
     # No TODO on the kind here, unlike nested_lines: `params.expect` spells an
     # array of hashes `#{name}: [[...]]`, which says definitively what the
     # equivalent permit call (`#{name}: [...]`) leaves ambiguous.