permittable 0.9.0 → 0.11.0

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,13 +374,19 @@ module Permittable
     end
 
     # The human-readable report: one block per controller, then the summary,
-    # then anything stale.
-    def format(entries, stale: {})
+    # 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.
+    def format(entries, stale: {}, unmatched: unmatched_ignores(entries))
       return "Permittable audit: no routed actions to report.\n" if entries.empty?
 
+      ignored, entries = entries.partition(&:ignored?)
       out = entries.group_by(&:controller).map { |key, group| controller_block(key, group) }
       out << summary_lines(summary(entries), rows: entries.length)
       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
 
@@ -242,9 +426,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 +442,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 +454,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

@@ -3,12 +3,11 @@ module Permittable
   # at class load — the same permittable_check_array a request goes
   # through, so the two cannot drift apart. Two seams are overridden:
   #
-  #   * `transform:` is NOT run. It is app code reshaping a value the client
-  #     sent, and a default is stored as the contract reads it, not as the
-  #     app reshapes it — so a contract with transform: hands out its
-  #     default untransformed, exactly as it always has, and nothing of the
-  #     app's runs at class load beyond the `validate:` an authored value was
-  #     already checked with.
+  #   * the field WHOSE default:/example: is being validated does not run
+  #     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.
   #   * 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.
@@ -26,6 +25,7 @@ module Permittable
     # [value as a request would get it, violations]
     def read_array(field, value)
       violations = []
+      @field = field
       read = permittable_check_array(field, value, path: field[:name].to_s, unknown: :ignore, violations: violations)
       [read, violations]
     end
@@ -36,8 +36,24 @@ module Permittable
 
     private
 
-    def permittable_transform(_field, value)
-      value
+    # Suppresses transform: for the field WHOSE default/example is being
+    # authored-validated (@field, compared by identity) — never for a
+    # sub-field nested inside it. A sub-field's own transform: is app code
+    # too, but it belongs to a DIFFERENT field's contract: an equivalent
+    # request sending that sub-field's value would run it, so the stored
+    # default has to match, or an omitted field and an explicitly-sent
+    # 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.
+    def permittable_transform(field, value)
+      return value if @field[:transform] || field.equal?(@field)
+
+      super
     end
 
     def permittable_violation(_field, param, code)

data/lib/permittable/generator.rb

@@ -297,33 +297,59 @@ module Permittable
     # nil, until one drafts or none is left: a draft rooted at the other
     # envelope in the file is a better starting point than no draft, and it
     # is what master drafted.
-    def for_controller(controller, source: nil, model: nil)
+    #
+    # `except:` names actions of DEFAULT_ACTIONS to leave out of the draft —
+    # the ones Permittable.audit_ignore names (see targets). With none left
+    # there is nothing to draft.
+    def for_controller(controller, source: nil, model: nil, except: [])
+      return nil if (DEFAULT_ACTIONS - except.map(&:to_sym)).empty?
+
       model ||= infer_model(controller)
       excluded = []
       loop do
         scan = scan(source, model: model, exclude: excluded)
-        result = draft(model: model, scan: scan)
+        result = draft(model: model, scan: scan, except: except)
         return result if result || !scan.found? || excluded.include?(scan.root)
 
         excluded << scan.root
       end
     end
 
+    # What `permittable:generate` drafts when no controller is named, as
+    # { controller => actions to leave out of its draft }: every controller
+    # with no contract yet, less what the audit ignores (Audit.ignore_reason).
+    # 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.
+    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) }
+        found[controller] = skipped unless skipped == DEFAULT_ACTIONS
+      end
+    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
     # TODO lines raises `a contract must declare at least one field` the
     # moment it is pasted.
-    def draft(model: nil, scan: nil)
+    def draft(model: nil, scan: nil, except: [])
       columns = columns_for(model)
       scan = nil unless scan&.found?
       return nil unless columns || scan
-      return column_draft(model, columns.values, []) unless scan
+      return column_draft(model, columns.values, [], except: except) unless scan
 
       shared = scanned_lines(scan, listed_columns(columns, :shared))
-      return fallback_draft(model, scan, columns) unless declares_field?(shared)
+      return fallback_draft(model, scan, columns, except: except) unless declares_field?(shared)
 
-      render(root: scan.root, model: columns && model) { |rule| scanned_lines(scan, listed_columns(columns, rule)) }
+      render(root: scan.root, model: columns && model, except: except) do |rule|
+        scanned_lines(scan, listed_columns(columns, rule))
+      end
     end
 
     # The columns as one rule drafts them (see DraftColumn#in_rule), each
@@ -356,7 +382,7 @@ module Permittable
     # `permit(policy(@post).permitted_attributes)` the scanner skips — says
     # nothing about the body, so it gets the model's root, as master drafted.
     # With no columns either there is nothing loadable to draft, so nil.
-    def fallback_draft(model, scan, columns)
+    def fallback_draft(model, scan, columns, except: [])
       return nil unless columns
 
       root = scan.root || (rootless_body?(scan) ? nil : default_root(model))
@@ -365,7 +391,7 @@ module Permittable
       # 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) } }
-      column_draft(model, drafted.values, scan_todo_lines(scan), root: root)
+      column_draft(model, drafted.values, scan_todo_lines(scan), root: root, except: except)
     end
 
     # Whether a rootless scan's calls carried at least one body field —
@@ -377,8 +403,10 @@ module Permittable
 
     # A draft from the columns, or nil when none of them has a contract type
     # to declare it with (render returns nil for a body of comments only).
-    def column_draft(model, columns, todos, root: default_root(model))
-      render(root: root, model: model) { |rule| column_lines(columns.map { |column| column.in_rule(rule) }) + todos }
+    def column_draft(model, columns, todos, root: default_root(model), except: [])
+      render(root: root, model: model, except: except) do |rule|
+        column_lines(columns.map { |column| column.in_rule(rule) }) + todos
+      end
     end
 
     def infer_model(controller)
@@ -400,6 +428,15 @@ module Permittable
     # top (draft_column) must not share this rescue: an error there would
     # otherwise discard EVERY column — the draft silently falls back to a
     # scan alone, or to nothing — for what is one column's problem.
+    #
+    # The rescue is scoped to ActiveRecord::ActiveRecordError, same as
+    # ColumnGuard.schema_reachable? and for the same reason: a genuinely
+    # unreachable schema (no database yet, table not migrated) degrades to
+    # no columns, but a real bug — a broken custom type adapter, a NameError
+    # from a typo — must keep surfacing instead of quietly emitting an empty
+    # draft. The defined? guard keeps this gem loadable without
+    # activerecord, same as schema_reachable? (a host without it duck-types
+    # `model:` and cannot raise an ActiveRecordError in the first place).
     def schema_columns(model)
       return nil unless model.respond_to?(:columns)
       return nil unless model.table_exists?
@@ -408,7 +445,9 @@ module Permittable
       # 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) }
-    rescue StandardError
+    rescue StandardError => e
+      raise unless defined?(ActiveRecord::ActiveRecordError) && e.is_a?(ActiveRecord::ActiveRecordError)
+
       nil
     end
 
@@ -507,7 +546,11 @@ module Permittable
     # can be CALLED as `Model.name`: a `first-status` enum's
     # `Order.first-statuses.keys` parses as `Order.first - statuses.keys`,
     # which runs a query when the draft loads. defined_enums reaches the
-    # same mapping by name.
+    # same mapping by name. The model is also checked for the accessor
+    # itself (mirrors ColumnGuard.enum_keys_expr): a name can pluralize to a
+    # valid identifier that the model does not actually answer to — renamed
+    # or otherwise excluded — and calling it would raise NoMethodError when
+    # the draft loads.
     def enum_for(model, name)
       return nil unless model.respond_to?(:defined_enums)
 
@@ -515,7 +558,11 @@ module Permittable
       return nil unless mapping
 
       plural = name.pluralize
-      accessor = METHOD_NAME.match?(plural) ? "#{model.name}.#{plural}" : "#{model.name}.defined_enums[#{name.inspect}]"
+      accessor = if METHOD_NAME.match?(plural) && model.respond_to?(plural)
+                   "#{model.name}.#{plural}"
+                 else
+                   "#{model.name}.defined_enums[#{name.inspect}]"
+                 end
       { mapping: mapping, accessor: accessor }
     end
 
@@ -986,12 +1033,20 @@ module Permittable
     # no field, which raises `a contract must declare at least one field`
     # when pasted. There is then nothing loadable to draft: nil, as for no
     # knowledge at all, which the rake task already skips.
-    def render(root:, model:, &lines)
+    #
+    # An action in `except` is dropped from the rule that declares it, and a
+    # rule left with no action is dropped: excepting :create from a split
+    # draft leaves the :update rule as drafted, with nothing required.
+    def render(root:, model:, except: [], &lines)
       shared = lines.call(:shared)
       return nil if shared.all? { |line| line.start_with?("#") }
 
       update = lines.call(:update)
       rules = shared == update ? [[DEFAULT_ACTIONS, shared]] : [[%i[create], lines.call(:create)], [%i[update], update]]
+      skipped = except.map(&:to_sym)
+      rules = rules.filter_map { |actions, body| [actions - skipped, body] unless (actions - skipped).empty? }
+      return nil if rules.empty?
+
       bodies = rules.map do |actions, body|
         "#{signature(root: root, model: model, actions: actions)}\n#{body.map { |line| "  #{line}\n" }.join}end\n"
       end

data/lib/permittable/json_schema.rb

@@ -114,8 +114,16 @@ module Permittable
       schema
     end
 
+    # deep_dup, not dup: .freeze is shallow, so the Array nested in an entry
+    # like :decimal ("type" => %w[string number]) stays live inside the frozen
+    # top-level Hash, and a shallow .dup would hand every :decimal field's
+    # exported schema that SAME Array. Nothing in this file mutates it in
+    # place (nullify! rebinds "type" to a new Array), but the exported
+    # document is caller-owned data, and a caller appending to it would
+    # otherwise silently rewrite the constant for every schema exported
+    # afterward in the process.
     def scalar_schema(field)
-      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).deep_dup
       apply_format_name!(schema, field)
       apply_in!(schema, field)
       apply_string_bounds!(schema, field)
@@ -151,7 +159,11 @@ module Permittable
       min, max = length_bounds(field[:length])
       schema["minItems"] = min if min
       schema["maxItems"] = max if max
-      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      # deep_dup here for the same reason as scalar_schema: a scalar `of:`
+      # otherwise hands every array field the SAME nested Array/Hash from
+      # SCALAR_SCHEMAS.
+      schema["items"] =
+        field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).deep_dup
       schema
     end
 
@@ -343,10 +355,22 @@ module Permittable
     # (silently changing a value outside any :decimal schema's justification)
     # or coerced through Float, where a non-finite BigDecimal (Infinity, NaN)
     # would crash JSON.generate.
+    #
+    # A `sensitive:` field's `default:`/`example:` are OMITTED rather than
+    # published: this exported document is the one channel meant to leave
+    # the app (client-generator tooling, a public docs endpoint), unlike the
+    # request log a `sensitive:` value is otherwise only redacted from, so
+    # shipping the real value here would defeat the redaction entirely.
+    # Omitting — rather than a placeholder string — matches how every other
+    # untranslatable or opaque fact in this file is handled: left out, with
+    # the `x-permittable-*` extension (here, `writeOnly`/`x-permittable-
+    # sensitive`) as the only signal that something is missing.
     def annotate(schema, field)
       decimal_mode = field[:kind] == JSON_TYPE ? :string : :number
-      schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
-      schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
+      unless field[:sensitive]
+        schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
+        schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
+      end
       schema["description"] = field[:desc] if field[:desc]
       if field[:sensitive]
         schema["writeOnly"] = true