permittable 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6009aed769f45203bb8053f4310d4ac986ec941815704e613f63bddf819bf92
-  data.tar.gz: 721cead2003e010c773e4bab9de20830d85f40182a049b8e4db6fa82d1f377d7
+  metadata.gz: d9b826995301bd0dc72ab69a6560ddfe58e13ae67323a252a9a506c21f61420d
+  data.tar.gz: 5e354c9e104237d9116591df08d4c1a58962f98d543d0f5ff6de983b96f3bc51
 SHA512:
-  metadata.gz: 5ff703088a1c1389cc49150521380c56f937d4ba0f99de0137e7390a91fa66a16bdad09092f0c65964b94e332bee170b17bdc6d7e9d03c11a7b2020f95953c78
-  data.tar.gz: 64b5097368d5df03d8dfacb4c9eb79cf6ecb08e2c0b933a80281201139e496f143f0336d886d4a4d33a15dfc0f2c7642f10ee5641e625874a80526717386d869
+  metadata.gz: c9cf62a2210a42cad9190f25ce259250c268dabf72bb966bae4110d2c627f27ce7a050a64f92c9e1729c9eb088d48077384b901481475a5cae077d1d802684ab
+  data.tar.gz: a6db0156d761c972ef0c9f6b41ef96e3fee3f0f48158ce01344b8a6ea39f9a8504dd2df015bcf3c379841420a66e857a42a2d0ff07d2d94902b49d89fec6b570

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 <!-- CHANGELOG.md -->
 
+## 0.5.1 (2026-09-02)
+<!-- title: nested input outside Rails -->
+
+Patch release. Checking how a contract handles a request with several top-level envelopes (`{ user: { ... }, address_attributes: { ... } }`) surfaced one crash and one unhelpful error; both are fixed below, and no behaviour of existing contracts changes.
+
+### Fixed
+- **Nested hash input crashed outside Rails.** `lib/permittable.rb` required `HashWithIndifferentAccess` but not the Hash core extension it needs to convert nested plain Hashes, so a standalone `Permittable::Contract` (or any host that loads only `permittable`) raised `NoMethodError: undefined method 'nested_under_indifferent_access'` on payloads like `{ user: { ... }, address_attributes: { ... } }`. Rails apps and the spec suite loaded the extension indirectly, which is why it went unnoticed; a spec now exercises a nested contract in a bare subprocess.
+- **`root:` rejects anything but one key at class load.** `root: [:user, :address_attributes]` used to leak `NoMethodError: undefined method 'to_sym' for Array`; it now raises a descriptive `ArgumentError` pointing at the recipe for several top-level envelopes — a rootless contract with one nested block per key. Specs pin that recipe, and pin that a rooted contract never sees the root's siblings (even under `unknown: :error`), matching `require(:user).permit`.
+
+## 0.5.0 (2026-09-02)
+<!-- title: the adoption on-ramp -->
+
+The adoption on-ramp. Writing the first contract for a legacy controller used to start from a blank page; now the gem drafts it from what the app already knows, and the contract can be asserted on in specs without dispatching a request.
+
+### Added
+- **`Permittable::Generator` and `bin/rails permittable:generate[controller]`** — drafts a `permit_params` contract for every controller that doesn't declare one (or one named controller), from the model's columns (type, NOT NULL, database default) plus any `params.require(...).permit(...)` calls found in the controller source. Drafts are emitted in **monitor mode**, so pasting one changes no behaviour; everything the generator cannot know for sure becomes a `# TODO` comment instead of a guess (non-column keys get `virtual: true`, unmappable column types and unparseable permit arguments stay visible as comments, database defaults are noted but deliberately **not** copied into `default:` — a contract default would overwrite columns on partial updates). Programmatic API (`Generator.draft(model:)`, `Generator.for_controller`, `Generator.scan`) works without Rails.
+- **RSpec matchers (`require "permittable/rspec"`)** — `permit_param(:age).for_action(:create).as(:integer).within(18..120)` asserts on the same frozen rule the validator enforces, so contracts are testable without a request. Chains: `for_action`, `as`, `as_array(of:)`, `required`/`optional`, `within`, `matching`, `with_length`, `with_default`, `virtual`, `sensitive`; dotted paths (`"address.zip"`, `"line_items.sku"`) walk nested and array blocks. Ambiguity fails loudly: `for_action` may be omitted only when the controller declares exactly one contract.
+- **`Permittable::Contract` — standalone contracts, no controller required.** `Contract.define(root: :user) { ... }` takes the identical field DSL and returns a callable object: `#call(hash)` never raises and returns a `Result` (`valid?` / `params` / `violations`); `#call!` returns the validated params or raises `InvalidParameters` with the same 400/422 status semantics a controller sees; `#json_schema` emits the contract as JSON Schema; `#rule` exposes the frozen data. Built for webhook payloads, job arguments, and service objects. Three deliberate differences from the concern: a `Contract` always enforces (the app-wide monitor mode is a request-rollout switch and is ignored), the router bookkeeping keys get no `unknown:` exemption, and nothing is memoized so one frozen contract is reusable everywhere.
+- **I18n fallback for violation messages** — a violation without a field-level `message:` now resolves copy from `permittable.errors.<code>` (covering the built-in codes, Symbol codes from `validate:`, missing `root:` keys, `unknown` keys, and `violate!` codes in `finalize`) before falling back to the bare `{ param:, code: }` shape. Resolution order: field `message:` → I18n → bare. Only String translations count; apps without I18n or without the keys are byte-for-byte unchanged.
+- **`docs/comparison.md`** — an honest comparison against `params.permit`, Rails 8's `params.expect`, rails_param, dry-validation, typed_params, and rswag, including the cases where each of those is the better choice, plus migration costs.
+- **`benchmark/overhead.rb`** — measures a full contract validation against the bare `params.permit` filter it replaces (on the reference payload the contract, casting and validating included, ran ~1.7× faster).
+
+All are additive — no behaviour of existing contracts changes.
+
 ## 0.4.0 (2026-08-24)
 <!-- title: monitor mode -->
 

data/README.md

@@ -54,7 +54,8 @@ A violating request never reaches your action:
 - [Violations and error responses](#violations-and-error-responses) · [Custom error messages](#custom-error-messages-message) · [Unknown parameters](#unknown-parameters)
 - [Output reshaping](#output-reshaping-transform-and-finalize) · [The schema-drift guard](#the-schema-drift-guard)
 - [Sensitive parameters](#sensitive-parameters-and-log-redaction) · [Instrumentation](#instrumentation)
-- [Monitor mode](#monitor-mode-roll-out-without-rejecting) · [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
+- [Monitor mode](#monitor-mode-roll-out-without-rejecting) · [Generating draft contracts](#generating-draft-contracts-permittablegenerate) · [Testing contracts](#testing-contracts-rspec-matchers)
+- [Standalone contracts](#standalone-contracts-no-controller) · [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
 - [API reference](#api-reference) · [Errors caught at class load](#errors-caught-at-class-load) · [Compatibility](#compatibility)
 
 ---
@@ -73,9 +74,12 @@ A violating request never reaches your action:
 | Checked against your schema at boot | ❌ | ❌ | ✅ |
 | Exports OpenAPI / JSON Schema | ❌ | ❌ | ✅ |
 | Report-only rollout mode | ❌ | ❌ | ✅ |
+| Drafts contracts from your schema | ❌ | ❌ | ✅ |
 
 The design rests on one idea: **a contract is data, not code.** It is declared once at the class level, frozen, inheritable, and introspectable. Everything else here follows from that — the drift guard can read it at boot, `finalize` can run on a bare object with no controller state, and the whole contract can be printed or tested without a request.
 
+A longer, honest comparison — `params.expect`, rails_param, dry-validation, typed_params, rswag, with the cases where each of them is the better choice, plus benchmarks and migration costs — lives in [docs/comparison.md](docs/comparison.md).
+
 ## Installation
 
 ```ruby
@@ -289,7 +293,24 @@ The rules:
 - `violate!` in `finalize` takes the same idea as a keyword: `violate!("user.ends_at", :before_start, message: "must be after starts_at")`.
 - A `message:` that is neither a String nor a code → String Hash raises at class load, like every other contract mistake.
 
-Fields without a `message:` are untouched — their details keep the bare `{ param:, code: }` shape. For full control over the response body itself (localization, RFC 9457, a different envelope), override `render_invalid_parameters` or define `render_error` as described above; `error.details` gives you the structured violations to build from.
+### Localizing default messages (I18n)
+
+App-wide copy for a violation code — without repeating `message:` on every field — comes from I18n, under `permittable.errors.<code>`:
+
+```yaml
+# config/locales/en.yml
+en:
+  permittable:
+    errors:
+      missing: "is required"
+      invalid_type: "is the wrong type"
+      inclusion: "is not an allowed value"
+      unknown: "is not a recognized parameter"
+```
+
+Resolution order per violation: the field's own `message:` (String, or the Hash entry for that code) → the app's `permittable.errors.<code>` translation → the bare `{ param:, code: }` shape. The lookup also covers a missing `root:`, `unknown` keys, Symbol codes returned by `validate:` (`permittable.errors.must_be_even`), and `violate!` codes in `finalize` (an explicit `violate!(..., message:)` still wins). Only a String translation counts — a missing key or a nested Hash falls back to the bare shape rather than leaking structure to clients. No I18n, no change: apps without the gem or the keys behave exactly as before.
+
+For full control over the response body itself (RFC 9457, a different envelope), override `render_invalid_parameters` or define `render_error` as described above; `error.details` gives you the structured violations to build from.
 
 ## Unknown parameters
 
@@ -421,13 +442,96 @@ Monitor-mode rules validate **eagerly in the `before_action`, regardless of `enf
 
 The rollout recipe:
 
-1. Write contracts for a legacy controller. The action code stays as-is.
+1. Write contracts for a legacy controller — or let [`permittable:generate`](#generating-draft-contracts-permittablegenerate) draft them. The action code stays as-is.
 2. Deploy with `PERMITTABLE_MODE=monitor`. Behaviour is unchanged; telemetry starts.
 3. Watch the dashboard. Every entry is a real client that would have been rejected — fix the contract, or wait for that traffic to drain.
 4. Flip to enforce, controller by controller. Every 422 you now return is one you already counted.
 
 [Exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) marks operations whose rule declares `mode: :monitor` with `x-permittable-mode: "monitor"` — the docs shouldn't promise a 422 the server doesn't yet send. Only the per-rule declaration is exported: the global `Permittable.mode` is runtime configuration, not contract data.
 
+## Generating draft contracts (`permittable:generate`)
+
+The blank-page problem, solved: the first draft of every contract can be generated from what the app already knows — the model's columns, and the `params.permit` calls already sitting in the controller.
+
+```sh
+bin/rails permittable:generate                      # every controller without a contract
+bin/rails "permittable:generate[UsersController]"   # one controller, even if covered
+```
+
+For each controller the task infers the model from `controller_name` (columns give types, NOT NULL gives `required`), scans the controller source for `params.require(...).permit(...)` calls (permitted keys give the field list and the `root:`), and prints a paste-ready draft:
+
+```ruby
+# Drafted by permittable:generate — review the TODOs, then deploy: monitor
+# mode reports violations (instrumentation + log) without rejecting requests.
+permit_params :create, :update, root: :user, model: User, mode: :monitor do
+  required :name, :string
+  optional :age, :integer
+  optional :status, :string # database default: "active"
+  optional :password_confirmation, :string, virtual: true # TODO: not a database column — confirm the type
+  array :tag_names, of: :string # TODO: confirm the element type
+end
+```
+
+The generator's one rule is **draft, don't guess** — everything it cannot know for sure stays visible instead of silently decided:
+
+- Drafts come out in **monitor mode**, so pasting one changes nothing until you flip it.
+- A permitted key that isn't a column becomes `virtual: true` with a TODO; a column type with no scalar equivalent (`json`, `binary`) becomes a TODO comment; a permit argument the conservative parser can't read (`*dynamic_keys`) is kept verbatim in a TODO instead of dropped.
+- A database default is noted in a comment but **not** copied into `default:` — a contract default is injected on every request that omits the field, which would overwrite columns on partial updates. The database already handles creation.
+- `key: [:a, :b]` in a permit call drafts as a nested block, with a TODO noting it may be an array of hashes.
+
+No Rails required for the core: `Permittable::Generator.draft(model: User)`, `.for_controller(controller, source: File.read(path))`, and `.scan(source)` are plain Ruby.
+
+Together with [monitor mode](#monitor-mode-roll-out-without-rejecting) this makes the whole adoption path one afternoon: generate drafts, paste, deploy monitoring, watch the dashboard, flip to enforce.
+
+## Testing contracts (RSpec matchers)
+
+Because a contract is data, it can be specified without dispatching a request. `require "permittable/rspec"` (in `spec_helper.rb`) auto-includes the matchers:
+
+```ruby
+RSpec.describe UsersController do
+  it "declares the create contract" do
+    expect(described_class).to permit_param(:email)
+      .for_action(:create).as(:string).matching(URI::MailTo::EMAIL_REGEXP).required
+    expect(described_class).to permit_param(:age).for_action(:create).as(:integer).within(18..120)
+    expect(described_class).to permit_param(:plan).for_action(:create).with_default("free")
+    expect(described_class).to permit_param(:tag_names).for_action(:create).as_array(of: :string)
+    expect(described_class).to permit_param("address.zip").for_action(:create).as(:string).optional
+    expect(described_class).not_to permit_param(:admin).for_action(:create)
+  end
+end
+```
+
+Chains: `for_action`, `as`, `as_array(of:)`, `required` / `optional`, `within` (`in:`), `matching` (`format:`), `with_length`, `with_default`, `virtual`, `sensitive`. Dotted paths walk nested blocks and array-of-hash blocks alike (`"line_items.sku"`).
+
+`for_action` picks the rule exactly like a request would (`permit_rule_for`), and may be omitted only when the controller declares a single contract — an ambiguous expectation raises instead of silently checking the wrong rule. Failure messages name what the contract actually declares.
+
+## Standalone contracts (no controller)
+
+The same DSL, callable on any Hash — webhook payloads, job arguments, service-object inputs, CSV rows:
+
+```ruby
+CreateUser = Permittable::Contract.define(root: :user) do
+  required :email, :string, format: URI::MailTo::EMAIL_REGEXP
+  optional :age,   :integer, in: 18..120
+  optional :plan,  :string, in: %w[free pro], default: "free"
+end
+
+result = CreateUser.call(payload)     # never raises
+result.valid?                          # => false
+result.violations                      # => [{ param: "user.age", code: "inclusion" }]
+result.params                          # validated HashWithIndifferentAccess; nil when invalid
+
+CreateUser.call!(payload)              # params, or raises Permittable::InvalidParameters
+CreateUser.json_schema                 # the contract as JSON Schema (draft 2020-12)
+CreateUser.rule                        # the frozen, introspectable rule data
+```
+
+Everything carries over — strict coercion, `""`/`nil` absence, defaults, `finalize` with `violate!`, `sensitive:` log-redaction registration, `invalid_parameters.permittable` instrumentation, 400-vs-422 status semantics for a missing `root:`. Three differences, all deliberate:
+
+- **A `Contract` always enforces.** Monitor mode is a request-rollout switch; standalone callers read the `Result` instead, so the app-wide `Permittable.mode` is ignored here.
+- **No router-key exemption.** `unknown: :error` flags a stray `action` or `controller` key — standalone input has no router to excuse.
+- **No memoization.** Every `#call` validates fresh, so one frozen contract is safely reusable and shareable (assign it to a constant).
+
 ## Exporting OpenAPI (docs that cannot drift)
 
 Because a contract is data, it has a third reader beyond the validator and the drift guard: an exporter that emits **OpenAPI 3.1** (whose request bodies are plain JSON Schema). The schema is generated from the same frozen data the server enforces, so — like the drift guard, pointed outward — the docs cannot lie:
@@ -500,6 +604,9 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | `Permittable::InvalidParameters` | Raised on violation; carries `#details` and `#status` |
 | `Permittable::JsonSchema` | Contract data → JSON Schema fragments (`.rule`, `.object`, `.field`) |
 | `Permittable::OpenAPI` | OpenAPI 3.1 assembly (`.document`, `.operations_for`, `.request_body_for`, `.components`) |
+| `Permittable::Generator` | Contract drafting (`.draft`, `.for_controller`, `.scan`) — see [generating draft contracts](#generating-draft-contracts-permittablegenerate) |
+| `Permittable::Contract` | [Standalone contracts](#standalone-contracts-no-controller) (`.define`, `#call`, `#call!`, `#json_schema`, `#rule`) |
+| `Permittable::Matchers` | RSpec matchers via `require "permittable/rspec"` — see [testing contracts](#testing-contracts-rspec-matchers) |
 
 ## Errors caught at class load
 

data/lib/permittable/contract.rb

@@ -0,0 +1,117 @@
+module Permittable
+  # A contract without a controller — the same field DSL, coercion, defaults,
+  # finalize, and violation vocabulary, callable on any Hash: webhook
+  # payloads, job arguments, service-object inputs, CSV rows.
+  #
+  #   CreateUser = Permittable::Contract.define(root: :user) do
+  #     required :email, :string, format: URI::MailTo::EMAIL_REGEXP
+  #     optional :age,   :integer, in: 18..120
+  #     optional :plan,  :string, in: %w[free pro], default: "free"
+  #   end
+  #
+  #   result = CreateUser.call(payload)   # => Result
+  #   result.valid?                       # => false
+  #   result.violations                   # => [{ param: "user.age", code: "inclusion" }]
+  #   result.params                       # validated HashWithIndifferentAccess, nil when invalid
+  #
+  #   CreateUser.call!(payload)           # params, or raises Permittable::InvalidParameters
+  #
+  # Differences from the controller concern, all deliberate:
+  #   * A Contract always ENFORCES. Monitor mode is a request-rollout switch;
+  #     standalone callers read the Result instead, so the app-wide
+  #     `Permittable.mode` is ignored here.
+  #   * The router's bookkeeping keys (controller/action/format) get no
+  #     exemption from `unknown:` checking — standalone input has no router.
+  #   * No memoization: every #call validates fresh, so one frozen Contract
+  #     is safely reusable and shareable.
+  #
+  # Everything else carries over, including `sensitive:` log-redaction
+  # registration, `invalid_parameters.permittable` instrumentation, 400
+  # semantics for a missing `root:`, and `#json_schema` for documentation.
+  class Contract
+    ACTION = "call".freeze
+
+    # The result of one #call: `params` is the cast, validated, defaulted
+    # HashWithIndifferentAccess (nil when invalid); `violations` is the same
+    # details array a controller's 422 would carry.
+    Result = Struct.new(:params, :violations, keyword_init: true) do
+      def valid?
+        violations.empty?
+      end
+
+      def invalid?
+        !valid?
+      end
+    end
+
+    class << self
+      alias define new
+    end
+
+    def initialize(root: false, unknown: :ignore, model: nil, desc: nil, &)
+      @host_class = Class.new do
+        include Permittable
+
+        attr_accessor :params
+
+        # Standalone input has no router, so nothing is exempt from the
+        # unknown-keys check (the concern exempts controller/action/format
+        # at the top level of request params).
+        def permittable_check_unknown(fields, hash, path:, unknown:, top_level:, violations:) # rubocop:disable Lint/UnusedMethodArgument
+          super(fields, hash, path: path, unknown: unknown, top_level: false, violations: violations)
+        end
+
+        # Instrumentation payload label (anonymous classes have no name).
+        def permittable_controller_name
+          "Permittable::Contract"
+        end
+      end
+      @host_class.permit_params(root: root, unknown: unknown, model: model, mode: :enforce, desc: desc, &)
+    end
+
+    # The frozen rule — same introspectable data a controller's
+    # `permit_rule_for` returns, readable by every contract consumer
+    # (JsonSchema, OpenAPI, the RSpec matchers' internals).
+    def rule
+      @host_class.permittable_contracts.last
+    end
+
+    # RSpec-matcher parity with controllers: `expect(MyContract).to
+    # permit_param(:email)` reads the registry through these. A standalone
+    # contract covers every "action", so the argument is irrelevant.
+    def permit_rule_for(_action = nil)
+      rule
+    end
+
+    def permittable_contracts
+      [rule]
+    end
+
+    def call(input)
+      Result.new(params: call!(input), violations: [].freeze)
+    rescue InvalidParameters => e
+      Result.new(params: nil, violations: e.details)
+    end
+
+    def call!(input)
+      host = @host_class.new
+      host.params = normalize_input(input)
+      host.permitted_params(ACTION)
+    end
+
+    # The request-body schema for this contract — JSON Schema draft 2020-12,
+    # identical to what the OpenAPI exporter emits for a controller rule.
+    def json_schema
+      JsonSchema.rule(rule)
+    end
+
+    private
+
+    def normalize_input(input)
+      return {} if input.nil?
+      return input if input.is_a?(Hash) || input.respond_to?(:to_unsafe_h)
+
+      raise ArgumentError, "#{LABEL}: Contract#call expects a Hash (got #{input.class})"
+    end
+  end
+end

data/lib/permittable/generator.rb

@@ -0,0 +1,218 @@
+module Permittable
+  # Drafts a permit_params contract from what the app already knows: the
+  # model's columns (types, NOT NULL, database defaults) and, when the
+  # controller source is available, the strong-parameters calls already in it
+  # (`params.require(:user).permit(:name, tags: [])`). The draft is a
+  # STARTING POINT, not an oracle — everything the generator cannot know for
+  # sure is marked with a TODO comment instead of guessed, and the whole
+  # contract is emitted in monitor mode so pasting it changes nothing until
+  # the TODOs are reviewed and the mode is flipped.
+  #
+  #   Permittable::Generator.for_controller(UsersController, source: File.read(path))
+  #   Permittable::Generator.draft(model: User)
+  #
+  # Rails apps get the same thing as a rake task:
+  #
+  #   bin/rails permittable:generate                      # every uncovered controller
+  #   bin/rails "permittable:generate[UsersController]"   # one controller
+  module Generator
+    DEFAULT_ACTIONS = %i[create update].freeze
+    SKIPPED_COLUMNS = %w[created_at updated_at].freeze
+
+    # Column type => contract type. Anything absent here (json, jsonb, hstore,
+    # binary, ...) has no faithful scalar representation and becomes a TODO
+    # comment rather than a guess.
+    COLUMN_TYPES = {
+      string: :string, text: :string, citext: :string, uuid: :string,
+      integer: :integer, bigint: :integer, float: :float, decimal: :decimal,
+      boolean: :boolean, date: :date, datetime: :datetime,
+      timestamp: :datetime, timestamptz: :datetime
+    }.freeze
+
+    # What a source scan recovered from existing permit calls. `scalars` are
+    # plain `:key` arguments, `arrays` are `key: []`, `nested` maps `key:
+    # [:a, :b]` onto its sub-keys, and `unparsed` keeps verbatim anything the
+    # conservative parser would otherwise have silently dropped.
+    Scan = Struct.new(:root, :scalars, :arrays, :nested, :unparsed, :calls, keyword_init: true) do
+      def found?
+        calls.positive?
+      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
+
+    # A permit key: `:name`, `"name"`, or `'name'` (quotes must match —
+    # anything else stays unparsed rather than guessed).
+    SCALAR_KEY = /\A(?::(\w+)|"(\w+)"|'(\w+)')\z/
+    ARRAY_ARG  = /\A(\w+):\s*\[\s*\]\z/m
+    NESTED_ARG = /\A(\w+):\s*\[([^\[\]]*)\]\z/m
+
+    module_function
+
+    # Merge every permit call found in `source` into one Scan. The first
+    # `.require(:root)` seen wins, matching how a controller normally sticks
+    # to one envelope across actions.
+    def scan(source)
+      result = Scan.new(root: nil, scalars: [], arrays: [], nested: {}, unparsed: [], calls: 0)
+      (source || "").scan(PERMIT_CALL) do |root, args|
+        result.calls += 1
+        result.root ||= root&.to_sym
+        split_args(args).each { |arg| classify_arg(result, arg) }
+      end
+      result
+    end
+
+    # Draft a contract for one controller: model inferred from
+    # controller_name (or passed explicitly), permit calls scanned from
+    # `source:` when given. Returns nil when there is nothing to draft from.
+    def for_controller(controller, source: nil, model: nil)
+      draft(model: model || infer_model(controller), scan: scan(source))
+    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.
+    def draft(model: nil, scan: nil)
+      columns = columns_for(model)
+      scan = nil unless scan&.found?
+      return nil unless columns || scan
+
+      root = scan ? scan.root : default_root(model)
+      body = scan ? scanned_lines(scan, columns) : column_lines(columns.values)
+      render(signature(root: root, model: columns && model), body)
+    end
+
+    def infer_model(controller)
+      return nil unless controller.respond_to?(:controller_name)
+
+      model = controller.controller_name.classify.safe_constantize
+      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).
+    def columns_for(model)
+      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) }.to_h { |c| [c.name, c] }
+    rescue StandardError
+      nil
+    end
+
+    # -- scan parsing -------------------------------------------------------
+
+    # Split a permit argument list on top-level commas only, so `address:
+    # [:city, :zip]` stays one argument.
+    def split_args(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?
+
+        parts.last << char
+      end
+      parts.map(&:strip).reject(&:empty?)
+    end
+
+    def classify_arg(result, arg)
+      if (key = scalar_key(arg))
+        result.scalars |= [key]
+      elsif (match = ARRAY_ARG.match(arg))
+        result.arrays |= [match[1].to_sym]
+      elsif (match = NESTED_ARG.match(arg))
+        classify_nested(result, match, arg)
+      else
+        result.unparsed |= [arg.gsub(/\s+/, " ")]
+      end
+    end
+
+    def classify_nested(result, match, arg)
+      keys = split_args(match[2]).map { |part| scalar_key(part) }
+      return result.unparsed |= [arg.gsub(/\s+/, " ")] if keys.any?(&:nil?)
+
+      result.nested[match[1].to_sym] = (result.nested[match[1].to_sym] || []) | keys
+    end
+
+    def scalar_key(part)
+      match = SCALAR_KEY.match(part)
+      match && (match[1] || match[2] || match[3]).to_sym
+    end
+
+    # -- drafting -----------------------------------------------------------
+
+    def default_root(model)
+      model.name.demodulize.underscore.to_sym
+    end
+
+    def signature(root:, model:)
+      parts = ["permit_params #{DEFAULT_ACTIONS.map(&:inspect).join(', ')}"]
+      parts << "root: :#{root}" if root
+      parts << "model: #{model.name}" if model
+      parts << "mode: :monitor do"
+      parts.join(", ")
+    end
+
+    def column_lines(columns)
+      columns.map { |column| column_line(column) }
+    end
+
+    def column_line(column)
+      type = COLUMN_TYPES[column.type]
+      return "# TODO: #{column.name} (#{column.type}) has no scalar contract type — declare it as a nested block or an array" unless type
+
+      line = "#{required_column?(column) ? 'required' : 'optional'} :#{column.name}, :#{type}"
+      line += " # database default: #{column.default.inspect}" unless column.default.nil?
+      line
+    end
+
+    # NOT NULL without a database default is the only case a client truly
+    # must send the field. A database default is deliberately NOT copied into
+    # the contract as `default:` — a contract default is injected on every
+    # 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 unless column.default.nil?
+
+      column.respond_to?(:default_function) && column.default_function ? false : true
+    end
+
+    def scanned_lines(scan, columns)
+      lines = scan.scalars.map { |name| scanned_scalar_line(name, columns) }
+      lines += scan.arrays.map { |name| "array :#{name}, of: :string # TODO: confirm the element type" }
+      scan.nested.each { |name, keys| lines += nested_lines(name, keys) }
+      lines + scan.unparsed.map { |arg| "# TODO: could not parse from the permit call: #{arg}" }
+    end
+
+    def scanned_scalar_line(name, columns)
+      column = columns && columns[name.to_s]
+      return column_line(column) if column
+      return "optional :#{name}, :string, virtual: true # TODO: not a database column — confirm the type" if columns
+
+      "optional :#{name}, :string # TODO: confirm the type"
+    end
+
+    def nested_lines(name, keys)
+      ["optional :#{name} do # TODO: drafted from `#{name}: [...]` — if this is an array of hashes, use `array :#{name} do`"] +
+        keys.map { |key| "  optional :#{key}, :string # TODO: confirm the type" } +
+        ["end"]
+    end
+
+    HEADER = "# Drafted by permittable:generate — review the TODOs, then deploy: monitor\n" \
+             "# mode reports violations (instrumentation + log) without rejecting requests.\n".freeze
+
+    def render(signature, body)
+      "#{HEADER}#{signature}\n#{body.map { |line| "  #{line}\n" }.join}end\n"
+    end
+  end
+end

data/lib/permittable/railtie.rb

@@ -15,6 +15,7 @@ module Permittable
 
     rake_tasks do
       load File.expand_path("tasks/openapi.rake", __dir__)
+      load File.expand_path("tasks/generate.rake", __dir__)
     end
   end
 end

data/lib/permittable/rspec.rb

@@ -0,0 +1,249 @@
+require "permittable"
+
+module Permittable
+  # RSpec matchers for asserting on declared contracts — the testing
+  # counterpart of "a contract is data": the matcher reads the same frozen
+  # rule the validator enforces, so a contract can be specified without
+  # dispatching a single request.
+  #
+  #   # spec_helper.rb (matchers auto-include when RSpec is defined)
+  #   require "permittable/rspec"
+  #
+  #   expect(UsersController).to permit_param(:age)
+  #     .for_action(:create).as(:integer).within(18..120)
+  #   expect(UsersController).to permit_param("address.zip").as(:string).optional
+  #   expect(UsersController).not_to permit_param(:admin).for_action(:create)
+  #
+  # `for_action` picks the rule exactly like a request would
+  # (`permit_rule_for`); it may be omitted only when the controller declares
+  # a single contract, so an ambiguous expectation fails loudly instead of
+  # silently checking the wrong rule.
+  module Matchers
+    def permit_param(path)
+      PermitParamMatcher.new(path)
+    end
+
+    class PermitParamMatcher
+      OPTION_LABELS = { in: "in:", format: "format:", length: "length:", default: "default:" }.freeze
+
+      def initialize(path)
+        @path = path.to_s
+        @action = nil
+        @expected = {}
+        @mismatches = []
+      end
+
+      # -- chains -----------------------------------------------------------
+
+      def for_action(action)
+        @action = action.to_s
+        self
+      end
+
+      def as(type)
+        @expected[:type] = type.to_sym
+        self
+      end
+
+      def as_array(of: nil)
+        @expected[:array] = true
+        @expected[:of] = of.to_sym if of
+        self
+      end
+
+      def required
+        @expected[:required] = true
+        self
+      end
+
+      def optional
+        @expected[:required] = false
+        self
+      end
+
+      def within(allowed)
+        @expected[:in] = allowed
+        self
+      end
+
+      def matching(regexp)
+        @expected[:format] = regexp
+        self
+      end
+
+      def with_length(spec)
+        @expected[:length] = spec
+        self
+      end
+
+      def with_default(value)
+        @expected[:default] = value
+        self
+      end
+
+      def virtual
+        @expected[:virtual] = true
+        self
+      end
+
+      def sensitive
+        @expected[:sensitive] = true
+        self
+      end
+
+      # -- RSpec protocol ---------------------------------------------------
+
+      def matches?(subject)
+        @subject = resolve_subject(subject)
+        rule = resolve_rule(@subject)
+        return false unless rule
+
+        @field = resolve_field(rule[:fields], @path.split("."))
+        return false unless @field
+
+        @mismatches = collect_mismatches(@field)
+        @mismatches.empty?
+      end
+
+      def failure_message
+        return "expected #{subject_name} to permit #{path_label}#{action_label}, but it #{@problem}" if @problem
+
+        if @field.nil?
+          declared = (@missing_among || []).map { |f| f[:name] }.join(", ")
+          return "expected #{subject_name} to permit #{path_label}#{action_label}, " \
+                 "but it is not declared (declared: #{declared})"
+        end
+
+        "expected #{subject_name} to permit #{path_label}#{action_label}, but:\n  #{@mismatches.join("\n  ")}"
+      end
+
+      def failure_message_when_negated
+        "expected #{subject_name} not to permit #{path_label}#{action_label}, but the contract declares it"
+      end
+
+      def description
+        descriptors = @expected.filter_map { |key, value| describe_check(key, value) }
+        label = "permit #{path_label}"
+        label += " (for ##{@action})" if @action
+        label += " #{descriptors.join(', ')}" unless descriptors.empty?
+        label
+      end
+
+      def supports_block_expectations?
+        false
+      end
+
+      private
+
+      # A controller CLASS carries the contract registry; an instance (a
+      # controller spec's `controller` / `subject`) resolves through its
+      # class. Anything answering permit_rule_for itself is used as-is.
+      def resolve_subject(subject)
+        return subject if subject.respond_to?(:permit_rule_for)
+        return subject.class if subject.class.respond_to?(:permit_rule_for)
+
+        raise ArgumentError, "#{LABEL}: the subject of permit_param must include Permittable (got #{subject.inspect})"
+      end
+
+      def resolve_rule(subject)
+        return resolve_rule_for_action(subject) if @action
+
+        contracts = subject.permittable_contracts
+        case contracts.length
+        when 0 then record_problem("declares no contracts")
+        when 1 then contracts.first
+        else
+          raise ArgumentError, "#{LABEL}: #{subject_name} declares #{contracts.length} contracts — " \
+                               "disambiguate with permit_param(...).for_action(:action)"
+        end
+      end
+
+      def resolve_rule_for_action(subject)
+        subject.permit_rule_for(@action) || record_problem("has no contract covering ##{@action}")
+      end
+
+      def record_problem(problem)
+        @problem = problem
+        nil
+      end
+
+      # Walks a dotted path through nested blocks and array-of-hash blocks
+      # alike, since both carry their sub-fields under :fields.
+      def resolve_field(fields, segments)
+        name = segments.first.to_sym
+        field = fields.find { |f| f[:name] == name }
+        if field.nil?
+          @missing_among = fields
+          return nil
+        end
+        return field if segments.length == 1
+
+        resolve_field(field[:fields] || [], segments.drop(1))
+      end
+
+      def collect_mismatches(field)
+        @expected.filter_map { |key, value| check_mismatch(field, key, value) }
+      end
+
+      def check_mismatch(field, key, value)
+        case key
+        when :type then type_mismatch(field, value)
+        when :array then "expected an array field, but it is declared with `#{field[:kind]}`" unless field[:kind] == :array
+        when :of then "expected an array of :#{value}, but it is of: :#{field[:of]}" unless field[:of] == value
+        when :required then required_mismatch(field, value)
+        when :virtual, :sensitive then "expected the field to be #{key}, but it is not" unless field[key]
+        else option_mismatch(field, key, value)
+        end
+      end
+
+      def type_mismatch(field, type)
+        if field[:kind] == :array
+          "expected type :#{type}, but :#{field[:name]} is an array — assert it with as_array(of: ...)"
+        elsif field[:kind] == :nested
+          "expected type :#{type}, but :#{field[:name]} is a nested hash"
+        elsif field[:type] != type
+          "expected type #{type.inspect}, but the contract declares #{field[:type].inspect}"
+        end
+      end
+
+      def required_mismatch(field, required)
+        actual = field[:required] ? "required" : "optional"
+        expected = required ? "required" : "optional"
+        "expected the field to be #{expected}, but it is #{actual}" unless actual == expected
+      end
+
+      def option_mismatch(field, key, value)
+        return if field.key?(key) && field[key] == value
+
+        label = OPTION_LABELS.fetch(key)
+        declared = field.key?(key) ? "declares #{label} #{field[key].inspect}" : "does not declare #{label}"
+        "expected #{label} #{value.inspect}, but the contract #{declared}"
+      end
+
+      def describe_check(key, value)
+        case key
+        when :type then "as :#{value}"
+        when :array then "as an array"
+        when :of then "of :#{value}"
+        when :required then value ? "required" : "optional"
+        when :virtual, :sensitive then key.to_s
+        else "#{OPTION_LABELS.fetch(key)} #{value.inspect}"
+        end
+      end
+
+      def subject_name
+        (@subject.respond_to?(:name) && @subject.name) || "the controller"
+      end
+
+      def path_label
+        @path.include?(".") ? @path.inspect : ":#{@path}"
+      end
+
+      def action_label
+        @action ? " for ##{@action}" : ""
+      end
+    end
+  end
+end
+
+RSpec.configure { |config| config.include Permittable::Matchers } if defined?(RSpec) && RSpec.respond_to?(:configure)

data/lib/permittable/tasks/generate.rake

@@ -0,0 +1,45 @@
+# Drafts Permittable contracts for controllers that don't declare one yet,
+# from each controller's model columns plus any params.permit calls in its
+# source. Drafts go to stdout (paste-ready); the summary goes to stderr.
+#
+#   bin/rails permittable:generate                      # every uncovered controller
+#   bin/rails "permittable:generate[UsersController]"   # one controller, even if covered
+namespace :permittable do
+  desc "Draft Permittable contracts from models and existing permit calls"
+  task :generate, [:controller] => :environment do |_t, task_args|
+    Rails.application.eager_load!
+
+    bases = []
+    bases << ActionController::Base if defined?(ActionController::Base)
+    bases << ActionController::API if defined?(ActionController::API)
+    controllers = bases.flat_map(&:descendants).uniq.select(&:name)
+
+    if task_args[:controller]
+      controllers = controllers.select { |c| c.name == task_args[:controller] }
+      abort "Permittable: no controller named #{task_args[:controller]} was found" if controllers.empty?
+    else
+      controllers = controllers.reject do |c|
+        c.respond_to?(:permittable_contracts) && c.permittable_contracts.any?
+      end
+    end
+
+    drafted = controllers.sort_by(&:name).count do |controller|
+      path = begin
+        Object.const_source_location(controller.name)&.first
+      rescue StandardError
+        nil
+      end
+      source = path && File.exist?(path) ? File.read(path) : nil
+      snippet = Permittable::Generator.for_controller(controller, source: source)
+      next false unless snippet
+
+      puts ["# ====", controller.name, path && "(#{path})", "===="].compact.join(" ")
+      puts snippet
+      puts
+      true
+    end
+
+    warn "Permittable: drafted #{drafted} contract#{'s' unless drafted == 1} — " \
+         "paste each into its controller and review the TODOs."
+  end
+end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.1".freeze
 end

data/lib/permittable.rb

@@ -2,6 +2,7 @@ require "active_support"
 require "active_support/concern"
 require "active_support/notifications"
 require "active_support/hash_with_indifferent_access"
+require "active_support/core_ext/hash/indifferent_access" # nested plain Hashes inside HWIA.new
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/string/filters"
@@ -180,6 +181,21 @@ module Permittable
 
       @mode = value
     end
+
+    # App-wide fallback copy for a violation code, looked up through I18n
+    # under permittable.errors.<code> ("missing", "inclusion", or any Symbol
+    # a validate: returned). Consulted only when the field declares no
+    # matching `message:` of its own, and only when the host app has I18n —
+    # without translations (or without I18n) details keep the bare
+    # { param:, code: } shape, so nothing changes for apps that don't opt
+    # in. Only a String translation counts; anything else (a nested Hash, a
+    # missing-translation object) is ignored rather than leaked to clients.
+    def default_message_for(code)
+      return nil unless defined?(::I18n) && ::I18n.respond_to?(:t)
+
+      message = ::I18n.t("permittable.errors.#{code}", default: nil)
+      message.is_a?(String) ? message : nil
+    end
   end
 
   # Raised when the request violates the matching contract. `details` is an
@@ -580,7 +596,10 @@ module Permittable
     # `message:` option.
     def violate!(param, code, message: nil)
       entry = { param: param.to_s, code: code.to_s }
-      entry[:message] = message.to_s if message
+      # Same resolution order as field violations: explicit message, then
+      # the app's I18n copy for the code, then the bare shape.
+      resolved = message ? message.to_s : Permittable.default_message_for(code)
+      entry[:message] = resolved if resolved
       @violations << entry
       throw :permittable_finalize_halt
     end
@@ -593,6 +612,10 @@ module Permittable
     #
     #   root:    key to unwrap first (`require(:user)` equivalent); false
     #            (default) reads top-level params. Missing root renders 400.
+    #            Exactly one key: a rooted contract never sees the root's
+    #            siblings (like `require(:user).permit`), so to accept
+    #            several top-level envelopes stay rootless and declare one
+    #            nested block per key.
     #   model:   a model class (or `true` to infer from controller_name)
     #            enabling the schema-drift check on every non-virtual scalar
     #            field.
@@ -609,6 +632,11 @@ module Permittable
     def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, mode: nil, desc: nil, &block)
       raise ArgumentError, "#{LABEL}: permit_params requires a block declaring the contract fields" unless block
 
+      unless root.nil? || root == false || root.is_a?(Symbol) || root.is_a?(String)
+        raise ArgumentError, "#{LABEL}: :root must be one key (Symbol or String) or false, got #{root.inspect} — " \
+                             "to accept several top-level keys, declare a rootless contract with one nested block per key"
+      end
+
       unknown = unknown.to_sym
       raise ArgumentError, "#{LABEL}: :unknown must be one of #{UNKNOWN_MODES.join(', ')}" unless UNKNOWN_MODES.include?(unknown)
 
@@ -820,11 +848,14 @@ module Permittable
     entry
   end
 
+  # Resolution order: the field's own `message:` (String, or Hash entry for
+  # this code), then the app's I18n copy (permittable.errors.<code>), then
+  # nothing — the bare { param:, code: } shape.
   def permittable_message_for(field, code)
     spec = field[:message]
-    return spec if spec.nil? || spec.is_a?(String)
+    return spec if spec.is_a?(String)
 
-    spec[code.to_sym]
+    (spec && spec[code.to_sym]) || Permittable.default_message_for(code)
   end
 
   def permittable_run_finalize(finalizer, result, violations)
@@ -849,7 +880,9 @@ module Permittable
     value = raw[rule[:root].to_s]
     return value if value.is_a?(Hash)
 
-    violations << { param: rule[:root].to_s, code: "missing" }
+    # No field declares the root, so message resolution can only come from
+    # I18n ({} has no :message).
+    violations << permittable_violation({}, rule[:root].to_s, "missing")
     nil
   end
 
@@ -958,7 +991,7 @@ module Permittable
     return if extra.empty?
 
     if unknown == :error
-      extra.each { |key| violations << { param: permittable_path(path, key), code: "unknown" } }
+      extra.each { |key| violations << permittable_violation({}, permittable_path(path, key), "unknown") }
     elsif respond_to?(:logger) && logger
       logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: " \
                   "#{extra.map { |key| permittable_path(path, key) }.join(', ')}")
@@ -985,6 +1018,13 @@ end
 require "permittable/json_schema"
 require "permittable/open_api"
 
+# Contract WRITER — drafts permit_params blocks from a model's columns and
+# existing params.permit calls (the permittable:generate rake task).
+require "permittable/generator"
+
+# Standalone contracts — the same DSL callable on any Hash, no controller.
+require "permittable/contract"
+
 # Boot-time integration (filter_parameters registration, the
 # permittable:openapi rake task), Rails apps only
 require "permittable/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -48,11 +48,15 @@ files:
 - README.md
 - lib/permittable.rb
 - lib/permittable/column_guard.rb
+- lib/permittable/contract.rb
 - lib/permittable/error_envelope.rb
 - lib/permittable/filter_parameter_registry.rb
+- lib/permittable/generator.rb
 - lib/permittable/json_schema.rb
 - lib/permittable/open_api.rb
 - lib/permittable/railtie.rb
+- lib/permittable/rspec.rb
+- lib/permittable/tasks/generate.rake
 - lib/permittable/tasks/openapi.rake
 - lib/permittable/version.rb
 homepage: https://github.com/VSN2015/permittable