permittable 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa679480fdac311694469096c7537926586e987ce2e7a724099611ec91dd3d2b
-  data.tar.gz: fa1785c674f0cbf388ce9f74b87f22344adef95cd5a5bfa6c81490fb8958a124
+  metadata.gz: 59d816740d54375ea14045959a2afb70dffee709e21350b914d69fcc115655c4
+  data.tar.gz: 233c21f86657a7643c5a8de70b83001e8f66b5e0ad3d1ae71e25a79b22883753
 SHA512:
-  metadata.gz: 66e7a85dad6e8029dbc8827b1a55ac14a297e3dc006315ffc66efc0e2f7dd6179ee6247e33f5de93a06d7fe08c3ff1205e30bf6dde6b16d93bfd381bdd3da813
-  data.tar.gz: fc0e4a920d62a687c960b808301841327bde86c85a2cf90c36c65e0ac61f133844e0733cd6ad3075298a8680d5a1360e9319495c4e60a9382449047bf6d76c0e
+  metadata.gz: 249dfeaf789c471b84589e5e49ee70148774fb03a5eaa3906a479088f7da68bc6d3f8a9b8d513e19c9f1fba18a62be1a6d9a68d1390b96c22c906e1ae208f002
+  data.tar.gz: a17c6c12cf879384624cd4f1eb654a05fc9cb5e641d821ee99461d459156744eb372bd51ced705588c6af7a5f2f713ee8285fb9f1c38a7eb42f2aaf6667a5867

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 <!-- CHANGELOG.md -->
 
+## 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 -->
+
+The rollout switch. Adopting contracts on a live API — or tightening an existing one — used to mean flipping unknown clients from "accepted" to "422" in a single deploy. A contract can now run in **monitor mode**: the full pipeline executes (unwrap, cast, validate, defaults), but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed. Deploy monitoring, dashboard the would-be rejections, then enforce controller by controller — every 422 you finally return is one you already counted.
+
+### Added
+- **`mode: :monitor` on `permit_params`, and an app-wide `Permittable.mode` default** (`:enforce` unless set; a rule's own `mode:` always wins, in both directions). On a violating request in monitor mode nothing raises and nothing renders: the `invalid_parameters.permittable` event fires with `mode: :monitor`, the logger warns with the offending paths, and `permitted_params` returns the **raw pass-through** — exactly what the client sent, no casts, no defaults, no transforms (a missing `root:` passes an empty hash; a rootless contract drops only the router's bookkeeping keys). Monitor rules validate **eagerly in the `before_action` regardless of `enforce:`**, so telemetry never depends on the action calling `permitted_params` — legacy actions still reading `params` directly are exactly the ones being monitored.
+- **`permittable_violations(action = nil)`** — the recorded violation details for the (memoized) validation of `action`, `[]` when the request was clean. The monitor-mode observable; under enforce it swallows its own trigger's raise, making "would this request fail?" a one-liner in tests.
+- **`mode:` key on the `invalid_parameters.permittable` payload** (`:enforce` / `:monitor`), so one subscriber can dashboard enforced rejections and monitored would-be rejections side by side. Additive — existing subscribers are unaffected.
+- **`x-permittable-mode: "monitor"`** on exported OpenAPI operations whose rule declares monitor mode — the docs must not promise a 422 the server doesn't yet send. Only the per-rule declaration is exported; the app-wide `Permittable.mode` is runtime configuration, not contract data.
+
+Contracts that don't opt in are byte-for-byte unaffected: the default mode is `:enforce` and the enforce path behaves exactly as before.
+
 ## 0.3.0 (2026-08-24)
 <!-- title: OpenAPI export -->
 

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)
-- [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)
 
 ---
@@ -72,9 +73,13 @@ A violating request never reaches your action:
 | Reshapes output | ❌ | ❌ | ✅ |
 | 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
@@ -108,10 +113,12 @@ params
 
 Validation is **lazy by default**: it runs on the first `permitted_params` call, so an action that never reads params never pays for it. Pass `enforce: true` to run it in a `before_action` instead, rejecting bad requests before the action body executes. Results are **memoized per action**.
 
+In [monitor mode](#monitor-mode-roll-out-without-rejecting) the same flow runs, but a violation is reported instead of raised and the request proceeds with the raw params passed through.
+
 ## Declaring a contract
 
 ```ruby
-permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, desc: nil, &contract)
+permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, mode: nil, desc: nil, &contract)
 ```
 
 | Option | Default | Meaning |
@@ -121,6 +128,7 @@ permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: fals
 | `model:` | `nil` | Model class, or `true` to infer from `controller_name`, enabling the [drift guard](#the-schema-drift-guard) |
 | `unknown:` | `:ignore` | `:ignore` / `:log` / `:error` — how to treat undeclared keys |
 | `enforce:` | `false` | `false` validates lazily on first use; `true` validates in a `before_action` |
+| `mode:` | `nil` | `nil` follows `Permittable.mode`; `:monitor` reports violations instead of rejecting — see [monitor mode](#monitor-mode-roll-out-without-rejecting) |
 | `desc:` | `nil` | Documentation only — becomes the operation description in [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) |
 
 `permit_params` is **repeatable**, and **the last matching rule wins**. Contracts behave like configuration: a base controller declares a catch-all, and a subclass overrides it for specific actions.
@@ -285,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
 
@@ -383,6 +408,130 @@ ActiveSupport::Notifications.subscribe("invalid_parameters.permittable") do |*,
 end
 ```
 
+## Monitor mode (roll out without rejecting)
+
+Adopting contracts on a live API — or tightening one field on an existing contract — has a chicken-and-egg problem: you cannot know what the 422s would break until you enforce them, and you dare not enforce them until you know. Old mobile app versions, third-party integrations, and forgotten cron jobs all send what they send. `mode: :monitor` resolves it: the full pipeline runs (unwrap, cast, validate, defaults), but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed.
+
+```ruby
+class OrdersController < ApplicationController
+  permit_params :create, root: :order, mode: :monitor do
+    required :sku,      :string
+    optional :quantity, :integer, in: 1..99
+  end
+
+  # The action doesn't have to change while monitoring — it can keep reading
+  # params the old way; the contract validates in the before_action.
+end
+```
+
+Or flip the whole app at once and pin controllers to their final mode one at a time — a rule's own `mode:` always beats the global, in both directions:
+
+```ruby
+# config/initializers/permittable.rb
+Permittable.mode = ENV.fetch("PERMITTABLE_MODE", "enforce").to_sym
+```
+
+On a violating request in monitor mode:
+
+- **Nothing raises and nothing renders** — the action runs.
+- The [`invalid_parameters.permittable` event](#instrumentation) fires with `mode: :monitor` in the payload (enforced violations carry `mode: :enforce`), and the logger warns with the offending paths. Point your existing subscriber at a dashboard and you have a per-controller rollout report.
+- `permitted_params` returns the **raw pass-through**: exactly what the client sent, untouched — no casts, no defaults, no transforms. A missing `root:` passes an empty hash (the envelope you asked for isn't there); a rootless contract drops only Rails' routing keys.
+- `permittable_violations` returns the recorded details (`[]` when the request was clean), if the action wants to branch on or tag the traffic.
+
+Monitor-mode rules validate **eagerly in the `before_action`, regardless of `enforce:`** — telemetry must not depend on the action calling `permitted_params`, since legacy actions still reading `params` directly are exactly the ones worth monitoring. (On a plain-Ruby host without `before_action`, validation stays lazy.)
+
+The rollout recipe:
+
+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:
@@ -422,7 +571,7 @@ How contracts map:
 
 Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
 
 Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
 
@@ -432,8 +581,9 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 
 | Method | Purpose |
 |---|---|
-| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Memoized per action. Raises `InvalidParameters` on violation, or `ArgumentError` when no contract covers the action |
-| `enforce_params_contract` | The `before_action` entry point. Only validates rules declared `enforce: true`. Public, so hosts can `skip_before_action` it |
+| `permitted_params(action = action_name)` | The cast, validated, defaulted `HashWithIndifferentAccess`. Memoized per action. Raises `InvalidParameters` on violation (in [monitor mode](#monitor-mode-roll-out-without-rejecting), returns the raw pass-through instead), or `ArgumentError` when no contract covers the action |
+| `permittable_violations(action = action_name)` | The violation details recorded by validating `action` — `[]` when clean. Triggers the same memoized validation; under enforce it swallows the raise, making "would this request fail?" a one-liner |
+| `enforce_params_contract` | The `before_action` entry point. Validates rules declared `enforce: true` and all [monitor-mode](#monitor-mode-roll-out-without-rejecting) rules. Public, so hosts can `skip_before_action` it |
 | `render_invalid_parameters(error)` | The `rescue_from` target. Renders via the host's `render_error` when defined, the inline envelope otherwise |
 
 ### Class methods
@@ -450,9 +600,13 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 |---|---|
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
 | `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
+| `Permittable.mode` / `Permittable.mode=` | App-wide default (`:enforce`) for rules that don't declare their own `mode:` |
 | `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
 
@@ -471,6 +625,7 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - An empty contract, or a nested block declaring no sub-fields
 - `finalize` declared twice, without a block, or inside a nested block
 - `permit_params` without a block, or an invalid `unknown:` mode
+- An invalid `mode:` (and `Permittable.mode =` rejects invalid values at assignment)
 - A `model:` that isn't an ActiveRecord class, or `model: true` that can't be inferred
 
 ## Compatibility
@@ -488,7 +643,7 @@ Using [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)? `Concer
 
 ```sh
 bundle install
-bundle exec rspec      # 112 examples
+bundle exec rspec      # 125 examples
 bundle exec rubocop
 ```
 

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/open_api.rb

@@ -135,6 +135,10 @@ module Permittable
       operation["description"] = rule[:desc] if rule[:desc]
       operation["requestBody"] = rule_request_body(rule)
       operation["responses"] = responses_for(rule)
+      # The docs must not promise a 422 the server doesn't yet send. Only
+      # the rule's own declaration is contract data — the app-wide
+      # Permittable.mode is runtime configuration the export can't see.
+      operation["x-permittable-mode"] = "monitor" if rule[:mode] == :monitor
       operation["x-permittable-catch-all"] = true if action == "*"
       operation
     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.3.0".freeze
+  VERSION = "0.5.0".freeze
 end

data/lib/permittable.rb

@@ -63,6 +63,21 @@ require "permittable/filter_parameter_registry"
 # action that never reads params never pays. `enforce: true` installs the
 # check as a before_action instead (reject before the action body runs).
 #
+# MONITOR MODE — the rollout switch. `mode: :monitor` on a rule (or
+# `Permittable.mode = :monitor` app-wide; a rule's own mode: wins) runs the
+# full pipeline but REPORTS violations instead of rejecting: the same
+# "invalid_parameters.permittable" event fires (payload mode: :monitor),
+# the logger warns, and permitted_params returns the raw params passed
+# through untouched — no casts, no defaults, no transforms — so behaviour
+# is identical to the pre-contract app (a missing root: passes an empty
+# hash; a rootless contract drops only the router's bookkeeping keys).
+# Monitor rules validate eagerly in the before_action regardless of
+# enforce:, because telemetry must not depend on the action calling
+# permitted_params — legacy actions still reading `params` directly are
+# exactly the ones being monitored — and monitoring can never halt the
+# request. `permittable_violations` reads the recorded details ([] when
+# the request was clean).
+#
 # Coercion is deliberately STRICT — ActiveModel::Type is not used, because its
 # casts are lenient by design ("abc".to_i == 0, Boolean.cast("abc") == true)
 # and silently corrupting untrusted input is exactly what a contract must not
@@ -119,6 +134,7 @@ module Permittable
   LABEL = "Permittable".freeze
   SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
   UNKNOWN_MODES = %i[ignore log error].freeze
+  MODES = %i[enforce monitor].freeze
   # Rails merges routing bookkeeping into params; a top-level (root: false)
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
@@ -144,6 +160,41 @@ module Permittable
     end
 
     attr_writer :filter_parameter_registry
+
+    # App-wide default for rules that don't declare their own mode:.
+    # :enforce (the default) rejects violating requests; :monitor reports
+    # them — same instrumentation event with payload mode: :monitor, plus a
+    # logger.warn — and lets the request proceed with the raw params passed
+    # through. This is the rollout switch for brownfield adoption: set it
+    # from an initializer (Permittable.mode =
+    # ENV.fetch("PERMITTABLE_MODE", "enforce").to_sym) and flip controllers
+    # to their final mode one at a time, since a rule's own mode: always
+    # wins over this default.
+    def mode
+      @mode || :enforce
+    end
+
+    def mode=(value)
+      value = value.to_sym
+      raise ArgumentError, "#{LABEL}: mode must be one of #{MODES.join(', ')}" unless MODES.include?(value)
+
+      @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
@@ -544,7 +595,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
@@ -564,14 +618,23 @@ module Permittable
     #            undeclared keys, at every nesting level.
     #   enforce: false (default) validates lazily on the first
     #            permitted_params call; true validates in a before_action.
+    #   mode:    nil (default) follows Permittable.mode; :enforce rejects
+    #            violating requests; :monitor reports them and passes the
+    #            raw params through (see MONITOR MODE in the module
+    #            comment).
     #   desc:    documentation only — carried on the rule for exporters
     #            (Permittable::OpenAPI); the runtime never reads it.
-    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, desc: nil, &block)
+    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
 
       unknown = unknown.to_sym
       raise ArgumentError, "#{LABEL}: :unknown must be one of #{UNKNOWN_MODES.join(', ')}" unless UNKNOWN_MODES.include?(unknown)
 
+      mode = mode&.to_sym
+      if mode && !MODES.include?(mode)
+        raise ArgumentError, "#{LABEL}: :mode must be one of #{MODES.join(', ')}, or nil to follow Permittable.mode"
+      end
+
       builder = ContractBuilder.new
       fields = builder.build(&block)
       raise ArgumentError, "#{LABEL}: a contract must declare at least one field" if fields.empty?
@@ -581,7 +644,7 @@ module Permittable
       register_sensitive_params(fields)
 
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
-               model: model_class, unknown: unknown, enforce: !!enforce, fields: fields,
+               model: model_class, unknown: unknown, enforce: !!enforce, mode: mode, fields: fields,
                finalize: builder.finalizer, desc: desc }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
@@ -657,21 +720,44 @@ module Permittable
     rule = self.class.permit_rule_for(action)
     raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
 
-    @permittable_validated[action] = validate_params_contract!(rule)
+    @permittable_validated[action] = validate_params_contract!(rule, action)
   end
 
   # before_action entry point (public so hosts can `skip_before_action
-  # :enforce_params_contract`). Only rules that opted in with
-  # `enforce: true` validate here.
+  # :enforce_params_contract`). Two kinds of rule validate here: those that
+  # opted in with `enforce: true`, and monitor-mode rules — monitoring must
+  # not depend on the action calling permitted_params (legacy actions still
+  # reading `params` directly are exactly the ones being monitored), and it
+  # can never halt the request because monitor mode never raises.
   def enforce_params_contract
     action = permittable_action_name
     return nil unless action
 
     rule = self.class.permit_rule_for(action)
-    permitted_params(action) if rule && rule[:enforce]
+    permitted_params(action) if rule && (rule[:enforce] || permittable_mode(rule) == :monitor)
     nil
   end
 
+  # The violation details recorded by validating `action` (default: the
+  # current action) — [] when the request satisfied the contract. Triggers
+  # the same memoized validation as permitted_params, so under monitor mode
+  # this is the request-level observable ("what would have been
+  # rejected?"); under enforce mode it swallows the raise and hands back
+  # the details, which makes "would this request fail?" a one-liner in
+  # tests.
+  def permittable_violations(action = nil)
+    action = (action || permittable_action_name).to_s
+    @permittable_violations ||= {}
+    unless @permittable_violations.key?(action)
+      begin
+        permitted_params(action)
+      rescue InvalidParameters
+        # validation recorded the details before raising
+      end
+    end
+    @permittable_violations.fetch(action)
+  end
+
   # rescue_from target — renders through the shared envelope (the host's
   # render_error when present, the identical inline shape otherwise).
   def render_invalid_parameters(error)
@@ -683,7 +769,7 @@ module Permittable
 
   private
 
-  def validate_params_contract!(rule)
+  def validate_params_contract!(rule, action)
     violations = []
     source = permittable_root_hash(rule, violations)
     result = ActiveSupport::HashWithIndifferentAccess.new
@@ -693,19 +779,53 @@ module Permittable
     end
     # finalize only sees a hash every field vouched for — never garbage.
     result = permittable_run_finalize(rule[:finalize], result, violations) if violations.empty? && rule[:finalize]
+    violations.each(&:freeze)
+    (@permittable_violations ||= {})[action] = violations.freeze
     return result if violations.empty?
+    return permittable_monitor_pass_through(rule, source, violations) if permittable_mode(rule) == :monitor
 
     raise_invalid_parameters!(violations, status: source ? :unprocessable_entity : :bad_request)
   end
 
+  # A rule's own mode: wins; otherwise the app-wide Permittable.mode.
+  def permittable_mode(rule)
+    rule[:mode] || Permittable.mode
+  end
+
+  # Monitor mode's violation path: emit the same instrumentation event the
+  # enforce path does (payload mode: :monitor) plus a warn line, then hand
+  # back exactly what the client sent — no casts, no defaults, no
+  # transforms — so behaviour is identical to the pre-contract app. A
+  # missing root: passes an empty hash through (the envelope you asked for
+  # isn't there); a rootless contract drops only the router's bookkeeping
+  # keys, mirroring their exemption from the unknown-keys check.
+  def permittable_monitor_pass_through(rule, source, violations)
+    permittable_instrument_violations(violations, mode: :monitor)
+    if respond_to?(:logger) && logger
+      logger.warn("#{LABEL}: [monitor] ##{permittable_action_name} would have been rejected: " \
+                  "#{permittable_violation_summary(violations)}")
+    end
+    return ActiveSupport::HashWithIndifferentAccess.new unless source
+
+    passed = ActiveSupport::HashWithIndifferentAccess.new(source)
+    rule[:root] ? passed : passed.except(*ROUTING_KEYS)
+  end
+
   def raise_invalid_parameters!(violations, status:)
-    violations.each(&:freeze)
+    permittable_instrument_violations(violations, mode: :enforce)
+    raise InvalidParameters.new("Invalid parameters: #{permittable_violation_summary(violations)}",
+                                details: violations, status: status)
+  end
+
+  def permittable_instrument_violations(violations, mode:)
     ActiveSupport::Notifications.instrument(
       "invalid_parameters.permittable",
-      controller: permittable_controller_name, action: permittable_action_name, details: violations
+      controller: permittable_controller_name, action: permittable_action_name, details: violations, mode: mode
     )
-    summary = violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
-    raise InvalidParameters.new("Invalid parameters: #{summary}", details: violations, status: status)
+  end
+
+  def permittable_violation_summary(violations)
+    violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
   end
 
   # One violation detail entry. A field's `message:` (String, or Hash keyed
@@ -718,11 +838,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)
@@ -747,7 +870,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
 
@@ -856,7 +981,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(', ')}")
@@ -883,6 +1008,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.3.0
+  version: 0.5.0
 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