concerns_on_rails 1.31.0 → 1.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 493ce0d913905625ffaabf033052a0ccc631aa22fe3c9a06a04c776ad4a80f67
-  data.tar.gz: 022bb7a0230e1c9c8ebc210c43245cf458c9248f3810f24f02c731695c0c046d
+  metadata.gz: a5638a56a20ce9b346dd013448af31656fe6925eaefbf8bd87ee8906c17825b4
+  data.tar.gz: b3feeb0feaab7f14bf5d03ea46a9e7a1a69f0d087173cf2fb0baa1efb2c86daa
 SHA512:
-  metadata.gz: 55cd86cfb3b04af3972060c2d4455dca7fe2ee7abfdccfa029c75ee6a9caee4b6700eeb128dd3f15aec5c52460af7ca5936935185593788d02df9c050044e3fa
-  data.tar.gz: 750dda120eb24d9e3d121a8e4ec1828e2d26303677f5758bc415f138fa4497845e1b67219203dc593ad5fe55a1a406e77d544b292f1639d4aa56546bb855010a
+  metadata.gz: 25623c6d25c7fafc8e8c4dfd5f16350df059a5f0bb2999c0d457b986cfcff1c55365f8e072ab5dd01cb9ae48e6226ff335a546f02c1521ca0c3934898e92c296
+  data.tar.gz: ad5dd6aa2c310c9d711fd9513e01488e79f164df54aa2accdbca8ab9a46f3c2fe296c0733c6b0c404c0df09147c28160f7c5177e0938b6637eb3037d71f1e363

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 <!-- CHANGELOG.md -->
 
+## 1.32.0 (2026-10-07)
+
+A dependency release (#127): the `permittable` floor rises to `>= 0.8`, and the Permittable docs
+are rewritten against permittable 0.10. It is a minor release because hosts still on permittable
+0.1–0.7 must upgrade it (the same rule as the Rails floor raise in 1.29.0). No code change, no
+new concerns and no migrations. 2723 examples, 0 failures, green on PostgreSQL, MySQL and every
+Rails line from 6.0 to 8.1.
+
+### Changed
+- **`permittable` dependency floor raised from `~> 0.1` to `>= 0.8, < 1`.** The Permittable
+  documentation (README section and docs page) was rewritten against permittable 0.10 — monitor
+  mode, `:json` fields, `nullable:`, `message:`/I18n copy, `format:` presets, field groups,
+  RFC 9457 output, the type-checking drift guard, the `permittable:generate`/`:audit`/`:openapi`
+  tasks, RSpec matchers and standalone contracts — and the old pin let a host resolve a 0.x that
+  had none of it. 0.8 is the floor because it is the newest line that still supports Rails 6.0
+  (0.9+ requires ActiveSupport >= 6.1), so the 6.0 CI line keeps resolving; the docs carry a
+  heads-up listing what a 0.8 host lacks and how Respondable's `:problem_details` and the gem's
+  own `Permittable.error_format = :problem` interact. No code change; the gem README stays the
+  canonical Permittable reference.
+
 ## 1.31.0 (2026-10-05)
 
 The fixes from two audits, each fix put through adversarial review rounds until a reviewer

data/README.md

@@ -101,7 +101,7 @@ Every concern below links to its section in this README **and** to its standalon
 | [🪝 WebhookVerifiable](#-webhookverifiable) | HMAC verification for inbound webhooks | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/webhook-verifiable) |
 | [🌅 Deprecatable](#-deprecatable) | RFC `Deprecation` / `Sunset` headers + 410 | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/deprecatable) |
 | [🗄️ Cacheable](#-cacheable) | HTTP conditional GET (ETag / 304) + `Cache-Control` | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/cacheable) |
-| [🛂 Permittable](#-permittable) | Typed, validated params contracts + schema-drift guard | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/permittable) |
+| [🛂 Permittable](#-permittable) | Typed, validated params contracts, schema-drift guard, OpenAPI export | [📖](https://vsn2015.github.io/concerns_on_rails/#/c/permittable) |
 
 ---
 
@@ -148,7 +148,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **2,483 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **2,723 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -158,7 +158,7 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 Add to your application's `Gemfile`:
 
 ```ruby
-gem "concerns_on_rails", "~> 1.31"
+gem "concerns_on_rails", "~> 1.32"
 ```
 
 Or pull the latest from GitHub:
@@ -2583,7 +2583,12 @@ etag_with { current_user&.role }             # => Cache-Control: private, max-ag
 
 ## 🛂 Permittable
 
-Declarative, **typed params contracts** — what strong parameters would be if it also knew types, bounds, defaults, and *why* a request was bad. `params.permit` (and Rails 8's `params.expect`) only answer "which keys may pass"; a Permittable contract additionally **casts** each field, **validates** it, applies **defaults**, and turns every failure into a machine-readable 422. Because the contract is class-level data (not code inside the action), it is introspectable — and can be checked against a model's schema at boot.
+Declarative, **typed params contracts** — what strong parameters would be if it also knew types, bounds, defaults, and *why* a request was bad. `params.permit` (and Rails 8's `params.expect`) only answer "which keys may pass"; a Permittable contract additionally **casts** each field, **validates** it, applies **defaults**, optionally **reshapes** the output, and turns every failure into a machine-readable 422. Because the contract is class-level data (not code inside the action), it has readers beyond the validator: a boot-time **schema-drift guard**, an **OpenAPI 3.1** exporter, **RSpec matchers**, a route-set **coverage audit**, a **draft generator**, and a standalone `Contract` for any Hash.
+
+> **Heads up — two things to know before relying on this section**
+>
+> 1. **Your lockfile, not this page, decides which features you have.** The pin is `>= 0.8, < 1`, so everything up to 0.8 (monitor mode, `:json`, `nullable:`, `message:`, field groups, matchers, generator, OpenAPI) is guaranteed, and an app that locked 0.8 keeps it until `bundle update permittable`. permittable 0.9+ requires ActiveSupport >= 6.1, so on Rails 6.0 Bundler stops at permittable **0.8**. That version lacks `format:` presets, `Permittable.check_column_types` and the enum rule, `Permittable.error_format = :problem`, `permittable:audit`, `params.expect` scanning in the generator, and the 0.10 canonical-numeric tightening (`"1_8"` and `" 99 "` still cast there). Everything else here applies. To make the newer surface a hard requirement, pin `gem "permittable", ">= 0.10"` in the app's Gemfile.
+> 2. **Two RFC 9457 switches exist — use one.** With [Respondable](#-respondable) included, Permittable's 422s render through `render_error`, so `respondable_by error_format: :problem_details` turns them into problem documents together with every other concern. The gem's own `Permittable.error_format = :problem` also renders RFC 9457 but deliberately **bypasses** `render_error`, so a controller with both set follows the gem's setting and ignores Respondable's envelope customisations.
 
 ```ruby
 class UsersController < ApplicationController
@@ -2591,10 +2596,12 @@ class UsersController < ApplicationController
 
   permit_params :create, :update, root: :user, model: User do
     required :name,  :string,  length: 1..80, normalize: :squish
-    required :email, :string,  format: URI::MailTo::EMAIL_REGEXP, normalize: :email
+    required :email, :string,  format: :email, normalize: :email
     optional :age,   :integer, in: 18..120
     optional :ssn,   :string,  sensitive: true          # auto-redacted from logs
     optional :plan,  :string,  in: %w[free pro], default: "free"
+    optional :nickname, :string, nullable: true         # explicit null clears the column
+    optional :metadata, :json, max_depth: 3, length: 0..32
     array    :tag_names, of: :string, length: 0..10
     optional :address do
       required :city, :string
@@ -2615,19 +2622,23 @@ end
 #                            { param: "user.age",  code: "inclusion" }] } }
 ```
 
-**The schema-drift guard** is the headline: with `model:` (a class, or `true` to infer from the controller name), every non-`virtual:` scalar field is checked against the model's columns **at controller class load** through the same `ColumnGuard` all model concerns use. A column dropped by a migration fails the deploy (production eager-loads controllers) with a teaching error — the missing-column message plus a ready-to-paste migration command plus the `virtual: true` escape hatch. Nested/array fields are implicitly virtual; the check skips gracefully when the schema is unreachable (`db:create`, `assets:precompile`). In CI, one `Rails.application.eager_load!` spec exercises every contract in the app.
+**The schema-drift guard** is the headline: with `model:` (a class, or `true` to infer from the controller name), every non-`virtual:` scalar field is checked against the model's columns **at controller class load**. A column dropped by a migration fails the deploy (production eager-loads controllers) with a teaching error — the missing-column message plus a ready-to-paste migration command plus the `virtual: true` escape hatch. Nested/array fields are implicitly virtual; the check skips gracefully when the schema is unreachable (`db:create`, `assets:precompile`). Opt into the type half with `Permittable.check_column_types = true` (families: text / numeric incl. boolean / temporal; a Rails `enum` must be declared `:string, in: Model.statuses.keys`). In CI, one `Rails.application.eager_load!` spec exercises every contract in the app.
+
+**Options** (`permit_params *actions, …`, repeatable; no actions = catch-all; **last matching rule wins**, subclasses inherit copy-on-write): `root:` (key to unwrap, `require(:user)`-style; missing root → **400**; default `false` = top-level params), `model:` (schema-drift guard), `unknown:` (`:ignore` default / `:log` / `:error` — undeclared keys at every nesting level; Rails' router/form/CSRF keys, the route's path params and ParamsWrapper's copy are exempt at the top level), `enforce:` (`false` = validate lazily on first `permitted_params` call, memoized per action; `true` = validate in a `before_action`), `mode:` (`:monitor` reports instead of rejecting — see below), `desc:` (OpenAPI operation description).
+
+**Field DSL**: `required`/`optional` `name, type` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, and `:json` — a free-form hash for `jsonb` columns, bounded by `length:` keys and `max_depth:`) with `in:` (Range, or a list snapshotted and cast at load — `in: Post.statuses` works), `format:` (Regexp or a preset: `:email`/`:uuid`/`:url`/`:slug`/`:hostname`), `length:`/`normalize:` (`:squish`/`:strip`/`:downcase`/`:upcase`/`:email` or a Proc; string fields only), `default:` (validated against the field's own contract at load time), `nullable:` (an explicit `null`/`""` yields `nil` instead of counting as absent — the one way to clear a column; wins over `default:`), `message:` (per-field copy, String or code → String; app-wide copy via I18n `permittable.errors.<code>`), `validate:` (Proc — falsy fails as `"invalid"`, a returned Symbol becomes the violation code), `transform:` (see below), `virtual:`, `sensitive:` (registers with the gem-wide filter_parameters registry, same pipe as Encryptable; cascades into nested blocks, `sensitive: false` opts a sub-field out), `desc:`/`example:` (docs). Nested hashes via a block; `array :name, of: :type` (or a block for arrays of hashes) with `length:` as element count — short-circuiting, and there is no default cap — and per-index violation paths (`items[1]`). Reusable **field groups**: `Permittable.fields { … }` + `use Group` (`optional: true` turns a create contract into a PATCH contract; `only:`/`except:`).
 
-**Options** (`permit_params *actions, …`, repeatable; no actions = catch-all; **last matching rule wins**, subclasses inherit copy-on-write): `root:` (key to unwrap, `require(:user)`-style; missing root → **400**; default `false` = top-level params), `model:` (schema-drift guard), `unknown:` (`:ignore` default / `:log` / `:error` — undeclared keys at every nesting level; Rails' `controller`/`action`/`format` keys are exempt at the top level), `enforce:` (`false` = validate lazily on first `permitted_params` call; `true` = validate in a `before_action` so the action body never runs on bad input).
+**Output reshaping** — the safe replacement for params-mutating before_actions, operating on the validated copy only (the request's `params` is never touched). `transform:` applies a callable **after** cast + validation to reshape that field's output — `transform: ->(v) { v.split(",") }` turns a validated delimited String into an Array (absent fields stay absent, a `default:` on a transformed field is handed out as authored, a partially-invalid array is never transformed). `finalize do |p| … end` (once per contract, top level only) runs after every field validated cleanly, receives the result hash, and returns the final shape — zip parallel fields into value objects, drop scaffolding keys. It executes on a bare runner, **not** the controller, so contracts stay pure; its one extra verb, `violate!(param, code, message: nil)`, records a violation and halts the block immediately — doubling as the cross-field validation seam ("ends_at after starts_at").
 
-**Field DSL**: `required`/`optional` `name, type` (`:string` default, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`) with `in:` (Range/Array), `format:`/`length:`/`normalize:` (`:squish`/`:strip`/`:downcase`/`:upcase`/`:email` or a Proc; string fields only), `default:` (validated against the field's own contract at load time), `validate:` (Proc — falsy fails as `"invalid"`, a returned Symbol becomes the violation code), `transform:` (see below), `virtual:`, `sensitive:` (registers with the gem-wide filter_parameters registry, same pipe as Encryptable). Nested hashes via a block; `array :name, of: :type` (or a block for arrays of hashes) with `length:` as element count and per-index violation paths (`items[1]`).
+**Coercion is strict** — deliberately not `ActiveModel::Type` ("abc".to_i == 0 and `Boolean.cast("abc") == true` silently corrupt untrusted input): a value the type can't faithfully represent is an `invalid_type` violation, numeric strings must be canonical (`"1_8"` and `" 99 "` are refused), dates must be complete (never filled in from today), booleans accept only `true/false/"true"/"false"/"1"/"0"/1/0`, and array/hash type-confusion (`?age[]=1`) is rejected instead of 500ing. `nil` and `""` are both **absent**: absent optional fields are *omitted* from the result (partial updates never nil-out columns), absent required fields violate, `default:` fills absence.
 
-**Output reshaping** — the safe replacement for params-mutating before_actions, operating on the validated copy only (the request's `params` is never touched). `transform:` (scalar/array fields) applies a callable **after** cast + validation to reshape that field's output — `transform: ->(v) { v.split(",") }` turns a validated delimited String into an Array (absent fields and `default:` values are untouched; a partially-invalid array is never transformed). `finalize do |p| … end` (once per contract, top level only) runs after every field validated cleanly, receives the result hash, and returns the final shape — zip parallel fields into value objects, drop scaffolding keys. It executes on a bare runner, **not** the controller, so contracts stay pure; its one extra verb, `violate!(param, code)`, records a violation and halts the block immediately — doubling as the cross-field validation seam ("ends_at after starts_at").
+**Adopting on a live API**: `bin/rails permittable:generate` drafts a contract per controller from the model's columns and the `params.permit`/`params.expect` calls already in the source (in monitor mode, every guess a visible TODO); `mode: :monitor` / `Permittable.mode = :monitor` runs the pipeline but **reports instead of rejecting** (notification with `mode: :monitor`, raw params passed through, `permittable_violations` for the action to branch on); `bin/rails permittable:audit` lists every routed action with its effective mode and flags write actions that accept a body with no contract (`audit[strict]` exits 1 — a CI gate); then flip to enforce controller by controller.
 
-**Coercion is strict** — deliberately not `ActiveModel::Type` ("abc".to_i == 0 and `Boolean.cast("abc") == true` silently corrupt untrusted input): a value the type can't faithfully represent is an `invalid_type` violation, booleans accept only `true/false/"true"/"false"/"1"/"0"/1/0`, and array/hash type-confusion (`?age[]=1`) is rejected instead of 500ing. `nil` and `""` are both **absent**: absent optional fields are *omitted* from the result (partial updates never nil-out columns), absent required fields violate, `default:` fills absence.
+**Beyond the controller**: `require "permittable/rspec"` gives `permit_param(:age).for_action(:create).as(:integer).within(18..120)` (the declaration) and `accept_params(payload).returning(hash)` / `reject_params(payload).with_violation("user.age", :inclusion)` (the behaviour) without dispatching a request; `Permittable::Contract.define(root: :user) { … }` runs the same DSL on any Hash (`call` → a `Result`, `call!` raises); `bin/rails permittable:openapi[path]` exports an **OpenAPI 3.1** document from the same frozen data the server enforces — anything JSON Schema can't express stays visible as an `x-permittable-*` extension instead of being mistranslated, and the output is deterministic so it can be committed.
 
-**Failure surface**: violations raise `Permittable::InvalidParameters` (carries `details` + `status`), auto-`rescue_from`d into the shared error envelope (`Respondable#render_error` when included, the identical inline JSON otherwise) and instrumented as `invalid_parameters.permittable` for dashboards. Introspect contracts via `permittable_contracts` / `permit_rule_for(action)`. Naming note: legacy InheritedResources controllers also define `permitted_params` — don't mix the two on one controller.
+**Failure surface**: violations raise `Permittable::InvalidParameters` (carries `details` + `status`; a missing/malformed `root:` is **400**, field violations **422**), auto-`rescue_from`d into the shared error envelope — `Respondable#render_error` when included (so `respondable_by error_format: :problem_details` makes them RFC 9457 along with the rest of the app), the identical inline JSON otherwise; the gem's own `Permittable.error_format = :problem` renders RFC 9457 too but bypasses `render_error`, so pick one switch. Instrumented as `invalid_parameters.permittable` (`controller`, `action`, `mode`, `details`), exactly once per action per request. Introspect contracts via `permittable_contracts` / `permit_rule_for(action)`. Naming note: legacy InheritedResources controllers also define `permitted_params` — don't mix the two on one controller.
 
-> Permittable ships as the standalone [`permittable` gem](https://github.com/VSN2015/permittable) (a runtime dependency of concerns_on_rails); `ConcernsOnRails::Controllers::Permittable` is an alias for `::Permittable`, with `sensitive:` registrations pooled into this gem's shared filter_parameters registry.
+> Permittable ships as the standalone [`permittable` gem](https://github.com/VSN2015/permittable) (a runtime dependency, `>= 0.8, < 1`; this section describes 0.10); `ConcernsOnRails::Controllers::Permittable` is an alias for `::Permittable`, with `sensitive:` registrations pooled into this gem's shared filter_parameters registry. Full reference: [the gem README](https://github.com/VSN2015/permittable#readme) · [docs page](https://vsn2015.github.io/concerns_on_rails/#/c/permittable).
 
 ---
 
@@ -2699,7 +2710,7 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite (2,723 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.31.0.gem      # install locally
+gem install ./concerns_on_rails-1.32.0.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.31.0".freeze
+  VERSION = "1.32.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.31.0
+  version: 1.32.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -108,16 +108,22 @@ dependencies:
   name: permittable
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1'
 description: A collection of plug-and-play ActiveSupport concerns for Rails models
   and Rails controllers
 email: