permittable 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 737a1777a6da7e8bcce3e969b82796279f0b5f1f51f3497abad696c4622f6951
-  data.tar.gz: 8c01787cc7081db7bbf6f4f0ce5a1f337b32e4d801d96bd6bd1f82678092c42e
+  metadata.gz: 7dc4908fbfa3e6b5e58441e97f3a1f73415a779447b06fd0d42b4a6fdc4154e4
+  data.tar.gz: 776776cac3cfd9288af6f591c96288acabb82707002017964a1ecee6b18dd9aa
 SHA512:
-  metadata.gz: 19320e84873a06b21eec376ddb236275ac7beaf217d29eed91e3dfab1e26c644c35538c6549ef57a73c6dd95b8bc9c5305aef8ed40075c3823f5d8a53dfd5404
-  data.tar.gz: 99cf9b0eee28ab54f31388fe647280b4f372022dc1bfc02ff01a09ef70032d68e0fde76816a51699fc9127b85f5230cd6938c2f4899981f954ec58d3e87a8de2
+  metadata.gz: 7f045ce704da2e70e4a1a85a4b7b8cdd2f5099733619779655885fc820b1fa03b6f4d99a7461e492d01147c15cc545fa268e46b11f13bfbd640cb334d3b98ff8
+  data.tar.gz: c82a67ca14285e04c35b218cd363f8280f2876e09faec983ded0d4aa81e30626d60e3fd67211ee0588e7f2b25a82da368ac97aac1f1ab505000256c1f5873e25

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 <!-- CHANGELOG.md -->
 
+## 0.13.0 (2026-10-24)
+<!-- title: the audit and the OpenAPI export follow mounted engines and Metal controllers, and a path variable is documented as one -->
+
+Two changes to what the audit and the OpenAPI export read, and one to how the export documents path variables. `permittable:audit`, `permittable:openapi` and `permittable:generate` now see controllers built directly on `ActionController::Metal`. The audit and the export follow routes mounted from a Rails engine, with the mount's path in front of the engine's. A rootless contract field that a route fills from the URL is documented as the path parameter it is.
+
+Minor rather than patch: there is no runtime change, `OpenAPI.rails_routes` callers now get more descriptors and a descriptor's `route:` may be an Array, but the audit and the OpenAPI document now see more, so `permittable:audit[strict]` can newly fail in an app that has an unguarded Metal controller or an unguarded route in a mounted engine, and an exported document changes for any app with a mounted engine, a Metal controller or a route-filled field.
+
+### Added
+- **`OpenAPI.rails_routes(app, engines: false)` reads the app's own route set alone.** `engines:` is a new keyword and defaults to `true`, which follows mounted engines (see the first entry under **Changed**). (#144)
+
+### Changed
+- **The audit and the OpenAPI export follow mounted Rails engines.** `OpenAPI.rails_routes` read only the app's own route set, so with `mount Billing::Engine => "/billing"` an unguarded `POST /billing/refunds` was never listed and `[strict]` exited 0, a covered `billing/invoices#create` was reported stale, and the export put billing operations under `x-permittable-controllers` instead of `paths`. `rails_routes(app, engines: true)` now follows each mounted engine, nested ones too, and puts the mount's path in front of the engine's, so a mount under `scope "(:locale)"`, at a dynamic `":tenant"`, or at `/` expands like any route. Routes reached through a mount carry `route: [mount, route]`, with one index per mount level (e.g. `[3, 0, 5]`), so `route:` may be an Array. Dispatch follows Rails: a mount ending in an optional segment lists no engine path Rails sends elsewhere, shadowing between app and engine routes follows Rails' single route order with each mount expanded in place, and a mount's `via:` drops the engine's other verbs. Rack mounts that are not engines are still skipped, a recursion guard stops cycles, and mounted gem engines appear in the audit's "outside the app root" section by default (while `Permittable.audit_ignore_outside_root` is on), without affecting `[strict]`. Callers that concatenate an app's and an engine's lists themselves should pass `engines: false`, which restores the old output. A parameter name used by both the mount and an engine route is not renamed: the path names it twice (`/t/{id}/{id}`) and the operation declares that one path parameter once. An engine route whose optional groups can all be absent (`post "(:locale(/:region))"`) is not documented as the mount's own path, which Rails answers with 404, and a lambda-constrained mount is still listed. (#144)
+- **`permittable:audit`, `permittable:openapi` and `permittable:generate` read `ActionController::Metal` controllers.** Each task collected controllers from `ActionController::Base.descendants` and `ActionController::API.descendants` only, so a lean webhook controller built on `Metal` was invisible: its unguarded `POST /hooks` had no audit row and did not fail `[strict]`, and one that included Permittable had its contracts enforced at runtime but missing from the export. All three tasks now read `Audit.rails_controllers`, which returns every named `ActionController::Metal` descendant less the framework's own abstract `ActionController::Base` and `ActionController::API`. (#108)
+
+### Fixed
+- **A rootless field a route fills from the URL is documented as the path parameter.** Rails merges the router's path parameters over the request's, so a rootless `required :id, :integer, in: 1..1000` on `resources :widgets, only: :update` is read from the URL, but the export gave the path parameter `{"type":"string"}` and put `id` in the request body's `required` list. The field now becomes the path parameter's schema, which stays required, and leaves the body's `properties` and `required`. Only a rootless contract does this, only for a scalar field, and only for a name the route's own path templates; an array, nested or `:json` field named like a variable stays in the body. With `unknown: :error`, every name the route templates stays in the body as an unconstrained, never-required property, so `{"id":7,"name":"x"}` is not documented as invalid. An action whose every field moved has no request body. A moved field loses `default:` and `nullable:`. A route that shares another's path pairs its variable names with the placed ones by position. (#136)
+
 ## 0.12.0 (2026-10-21)
 <!-- title: stricter numbers, dates and class-load checks, and matchers that stop passing for the wrong reason -->
 

data/README.md

@@ -904,7 +904,7 @@ The setting is app-wide, not per-contract, because the error format of an API is
 
 Under `:log` that bound is the whole record: nothing else names an undeclared key, so beyond the tenth only the count survives. Where you need every name — auditing what a client really sends during a rollout — use `unknown: :error` in monitor mode, which records all of them in `details` and in the instrumentation payload without rejecting the request.
 
-Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token` (or whatever `config.action_controller.request_forgery_protection_token` renames it to), `_method`, `utf8`, and the submit button's name from an ordinary form POST: `commit` from `f.submit` / `submit_tag`, `button` from `f.button` / `button_tag` (sent as `button=` when the `<button>` has no value). All eight are exempt at the top level. So is the click point of an image submit: `image_submit_tag("save.png")` renders an `<input type="image">` with no name, and a browser submitting through it posts where it was clicked as `x=12&y=7` (or `save.x=12&save.y=7` when the tag is named `"save"`, which Rack keeps as those literal keys). `x` and `y` are ordinary names a contract may really be sent, so they are exempt only as a pair, both present and both plain digits (never negative or fractional); a lone `x`, or a pair that is not digits, is flagged as usual, and a contract that *declares* `x` or `y` has it validated as usual and sees the other flagged unless it declares that too. A bracketed image-submit name is not covered (`name: "user[save]"` is parsed by Rack as `{"user"=>{"save"=>{".x"=>..}}}`, nested rather than top level), just as only the top-level `commit` and `button` are. So are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `unknown: :error` flags what the *client* got wrong rather than what the framework added. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there — and a standalone `Contract` exempts nothing at all, having neither a router, a form, nor a request.
+Rails merges its own keys into `params`: `controller`, `action`, and `format` from the router, plus `authenticity_token` (or whatever `config.action_controller.request_forgery_protection_token` renames it to), `_method`, `utf8`, and the submit button's name from an ordinary form POST: `commit` from `f.submit` / `submit_tag`, `button` from `f.button` / `button_tag` (sent as `button=` when the `<button>` has no value). All eight are exempt at the top level. So is the click point of an image submit: `image_submit_tag("save.png")` renders an `<input type="image">` with no name, and a browser submitting through it posts where it was clicked as `x=12&y=7` (or `save.x=12&save.y=7` when the tag is named `"save"`, which Rack keeps as those literal keys). `x` and `y` are ordinary names a contract may really be sent, so they are exempt only as a pair, both present and both plain digits (never negative or fractional); a lone `x`, or a pair that is not digits, is flagged as usual, and a contract that *declares* `x` or `y` has it validated as usual and sees the other flagged unless it declares that too. A bracketed image-submit name is not covered (`name: "user[save]"` is parsed by Rack as `{"user"=>{"save"=>{".x"=>..}}}`, nested rather than top level), just as only the top-level `commit` and `button` are. So are the route's **path parameters** (`PATCH /users/1` merges `id`, which the exported OpenAPI documents as a path parameter rather than a body field); a contract that *declares* `id` has it validated as usual, since the URL really carried it, and the export then documents that field as the path parameter's schema (`required :id, :integer, in: 1..1000` becomes `{"type":"integer","minimum":1,"maximum":1000}`) and leaves it out of the request body, `required` list included, so a body without `id` is valid. Only a rootless contract does this, and only for a name the route templates; a `root:` contract's `id` is a body field and stays one, and so does an `array`, nested or `:json` field, since no URL segment can be one. Under `unknown: :error` the body schema forbids undeclared keys, but every name the route templates stays in it as a property that takes any value and is never required, declared or not: `PATCH /users/1` with `{"id":1,"name":"x"}` is accepted, because the path parameter is exempt and the URL's `id` overwrites the body's. **ParamsWrapper's copy of a JSON body** under the controller's wrapper key (`user` for `UsersController`) goes further: when Rails made that copy, a rootless contract does not see the key at all, because the client never sent it. So an undeclared wrapper key is not flagged, and a scalar or array field that happens to share the wrapper's name (`optional :feedback, :string` on `FeedbackController`) is simply absent, rather than failing as `invalid_type` against Rails' copy of the whole body. The one exception is a rootless contract that declares the wrapper key as a hash container — a nested block (`required :user do ... end`) or `:json`. That contract is reading the copy on purpose, like a `root:` spelled as a field, so the copy is kept and validated as that field. A client that sends `user` itself is checked like any other key: validated if declared, flagged if not. That holds whether the wrapper name is configured as a String or as a Symbol (`wrap_parameters :user`). Either way `unknown: :error` flags what the *client* got wrong rather than what the framework added. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there — and a standalone `Contract` exempts nothing at all, having neither a router, a form, nor a request.
 
 All of this changes what is *checked* only. Monitor mode still hands back the form keys, the path parameters and the wrapper's copy in its raw pass-through, where behaving exactly like the pre-contract app is the whole promise and a legacy action may read `params[:id]` or `_method` itself; only the router's three are dropped there.
 
@@ -1241,7 +1241,7 @@ No Rails required for the core: `Permittable::Generator.draft(model: User)`, `.f
 
 A controller declaring `permit_params :create` looks adopted. If it also answers `PATCH`, that action is validating **nothing** — and until now nothing in the gem said so. [`permittable:generate`](#generating-draft-contracts-permittablegenerate) only notices controllers with no contract at all, and the [OpenAPI export](#exporting-openapi-docs-that-cannot-drift) documents what exists rather than what is missing.
 
-The audit crosses the contract registry with the **route set**, so a half-covered controller is as visible as an uncovered one:
+The audit crosses the contract registry with the **route set**, so a half-covered controller is as visible as an uncovered one. It reads every controller a route can reach: `ActionController::Base` and `::API` subclasses, and bare `ActionController::Metal` ones such as a lean webhook endpoint. The export and the generator read the same list.
 
 ```sh
 bin/rails permittable:audit             # the table plus a summary
@@ -1288,7 +1288,7 @@ A `config.exceptions_app = routes` setup (`match "/404", to: "errors#not_found",
 
 Under `[strict]` the task aborts on these rows. Either route the catch-all GET-only, as above, or add `application#not_found` to the [ignore list](#ignoring-controllers-and-actions). Don't declare a contract on the catch-all to silence the gate. Under monitor mode it validates eagerly, so a malformed JSON POST answers 400 instead of 404. The OpenAPI export would also gain a fake `/{path}` endpoint.
 
-The table lists a row for every verb on every path; the summary counts routes. A route with an optional segment, such as anything under `scope "(:locale)"`, lists each path it expands to (`/users` and `/{locale}/users`), but it is one route, so one unguarded `POST` counts once and the summary line says `N routed actions in M rows`. Rows are collapsed by controller, action, route index and verb; the index is a position within one `rails_routes` call, so audit concatenated route lists (an app's and an engine's) separately, or give them distinct `route:` values. Two separate routes to the same action (`post "/users"` and `post "/admin/users"`) count as two, because each one is a way in.
+The table lists a row for every verb on every path; the summary counts routes. A route with an optional segment, such as anything under `scope "(:locale)"`, lists each path it expands to (`/users` and `/{locale}/users`), but it is one route, so one unguarded `POST` counts once and the summary line says `N routed actions in M rows`. Rows are collapsed by controller, action, route index and verb; the index is a position within one `rails_routes` call (a route reached through a mounted engine is `[mount, route]`; see below), so a caller that concatenates route lists itself should pass `engines: false` for each, and audit them separately or give them distinct `route:` values. Two separate routes to the same action (`post "/users"` and `post "/admin/users"`) count as two, because each one is a way in.
 
 Controllers that never included `Permittable` are audited too — those are the ones worth finding. Everything is plain Ruby over the frozen registry plus route descriptors, so `Permittable::Audit.entries(controllers:, routes:)` works without Rails. It takes `ignore:` and `root:` too, which default to `Permittable.audit_ignore` and `Rails.root` (see below).
 
@@ -1312,7 +1312,9 @@ An entry is a controller path the way Rails routes it (the controller half of `b
 
 Assign the whole list. It is frozen, so add to it with `Permittable.audit_ignore += ["webhooks#receive"]`, which is validated too.
 
-**Controllers outside `Rails.root` are ignored by default.** These are engines and gems: ActiveStorage, ActionMailbox, Devise, and Rails' own `rails/*` controllers. An app can't keep a contract in a gem's controller. The audit locates a controller by the file that defines its class (`Module#const_source_location`). A gem installed inside the app still counts as a gem; `bundle config path vendor/bundle` does this, and so do CI caches. A controller whose source can't be located is audited. To audit gem controllers like your own:
+**Mounted engines are part of the app.** `mount Billing::Engine => "/billing"` makes every route the engine draws a URL of the app, so `rails_routes` follows each mounted Rails engine (nested ones too) and puts the mount's path in front of the engine's: an unguarded `POST /billing/refunds` fails `[strict]`, and a covered action in the engine is not reported as stale. A mount at a dynamic `at: ":tenant"`, or under `scope "(:locale)"` at `/blog`, joins like any other path. A mount whose path ends in an optional segment (`scope "(:locale)"` over a mount at `/`, or `at: "/m(/:slug)"`) lists the engine's routes with the segment only, as Rails does: it matches the mount's own path first, the segment present before absent, so `/posts` is the locale `posts` asking for the engine's root, and the engine's `/posts` is reached as `/{locale}/posts`. A constrained segment (`locale: /en|fr/`) keeps both. A mount's `via:` limits the verbs: `mount Shop::Engine, at: "/g", via: :get` leaves out the engine's `POST` routes, which answer 404. An engine mounted twice is two routes to its actions. Routes are judged in Rails' order with the mount standing where it is drawn: an app route ahead of the mount answers before the engine is asked, an engine route that matches answers and hides an app route behind the mount, and a request the engine has no route for goes on to the next route. A constrained mount, like any constrained route, hides no route behind it. A Rack mount that is not an engine (Sidekiq::Web, a lambda) has no routes to read and is skipped. `Permittable::OpenAPI.rails_routes(app, engines: false)` reads the app's own route set alone. One limit: a parameter name used by both the mount and an engine route (`/{id}/.../{id}`) is not renamed, so the template names it twice (`/t/{id}/{id}`) and the operation declares that one path parameter once.
+
+**Controllers outside `Rails.root` are ignored by default.** These are gems and engines installed as gems (an engine kept inside your app counts as yours): ActiveStorage, ActionMailbox, Devise, and Rails' own `rails/*` controllers. An app can't keep a contract in a gem's controller. The audit locates a controller by the file that defines its class (`Module#const_source_location`). A gem installed inside the app still counts as a gem; `bundle config path vendor/bundle` does this, and so do CI caches. A controller whose source can't be located is audited. To audit gem controllers like your own:
 
 ```ruby
 Permittable.audit_ignore_outside_root = false
@@ -1457,7 +1459,9 @@ Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 
 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 construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); 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 — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string`, because the route set doesn't say what an `:id` is and the exporter won't invent it. 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 construct with no faithful ECMA-262 spelling is exported as `x-permittable-pattern` rather than a mistranslated `pattern`: a Ruby-only escape or flag, one ECMA-262 reads differently or refuses to compile at all (`{,3}`, `&&` in a class, a backreference, the word boundary `\b`), or one that cannot be carried once folded into the rest of its own character class (`\S` beside a member other than `\s`) — but **not** a hyphen right after a completed range (`[a-c-e]`), which both dialects read the same way and export unchanged. This also covers a regexp anchored with `^`/`$`, which in Ruby anchor a **line** and in ECMA-262 anchor the whole string, so `/^\d{5}$/` accepts `"evil\n12345"` at runtime and publishing that source would promise a stricter rule than the server enforces (use `\A`/`\z`, which translate exactly); `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`, and a rule's `finalize` block `x-permittable-finalize` (on the rule's own object, inside the `root:` wrapper when there is one, and on the operation too, so the marker survives an operation that has no request body); 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 — or whose path-and-verb slot another controller already claimed, which one document cannot represent twice, or whose route an earlier one shadows (below) — land in `x-permittable-controllers` instead of being dropped. A templated path segment is declared as a path `parameter` of type `string` unless the contract says more, because the route set doesn't say what an `:id` is and the exporter won't invent it: a rootless contract's *scalar* field of the same name is that parameter's schema (see [Unknown parameters](#unknown-parameters) for what that does to the request body), minus any `default:` and `nullable:`, since the URL always supplies a non-null value. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+
+**Mounted engines are documented under their mount point.** The task follows each `mount Billing::Engine => "/billing"` into the engine's routes, so an engine's operations land in `paths` as `/billing/...` (a dynamic mount point becomes a `{tenant}` template). A Rack mount that is not an engine is skipped. See [Auditing coverage](#auditing-coverage-permittableaudit) for the details and the one limit on shared parameter names.
 
 **Paths are the URLs Rails dispatches.** An optional segment expands into each path it stands for, read the way Rails matches it: present before absent, left to right, constraints included. So `get "x(/:a)(/new)"` documents no `/x/new`, because Rails reads that URL as `a = "new"`, unless a constraint on `:a` rejects `"new"`. Rails squeezes a run of slashes to one before it matches, so a variant an absent leading group leaves with two in a row is no URL: `get "(:locale)(/:theme)"` documents `/`, `/{locale}` and `/{locale}/{theme}`, never `//{theme}`, and `get "(:locale(/:region))"` documents no `/`, which Rails answers with a 404. OpenAPI forbids two paths that differ only in their variable names, and two routes can produce them: under `scope "(:locale)"` a root is `/{locale}` and a `get ":slug"` is `/{slug}`. Such paths are one path, spelled as the route Rails tries first spells it. A later route under another verb is placed there too, and carries its own spelling in `x-permittable-path`. One under the same verb is shadowed: Rails sends that URL to the earlier route, and reaches the later one only when the earlier route's constraints turn the request away. It is listed in the earlier operation's `x-permittable-shadows` instead of being emitted as a second path, and its operation lands in `x-permittable-controllers` if it has no other path. A variant of one route that a constraint keeps reachable is listed the same way: `x(/:a)(/:b)` with `a: /\d+/` sends `/x/foo` to `:b`, so `/x/{a}` lists `/x/{b}`.
 

data/lib/permittable/audit.rb

@@ -142,6 +142,22 @@ module Permittable
       end
     end
 
+    # Every controller class a Rails route can reach, for the rake tasks:
+    # ActionController::Metal and everything below it. The tasks used to
+    # collect ActionController::Base and ::API descendants only, so a bare
+    # Metal controller — the usual shape of a lean webhook endpoint, and a
+    # host this gem supports — had no audit row, never counted against
+    # [strict], and its contracts were missing from the export. Base and API
+    # themselves are Metal descendants too; they are the framework's abstract
+    # bases, which no route names, and the old lists never held them.
+    # Anonymous classes cannot be routed to, so only named ones are kept.
+    def rails_controllers
+      return [] unless defined?(::ActionController::Metal)
+
+      frameworks = %w[ActionController::Base ActionController::API]
+      ::ActionController::Metal.descendants.uniq.select { |controller| controller.name && !frameworks.include?(controller.name) }
+    end
+
     # The root a controller's source must be inside to be audited:
     # Rails.root, unless Permittable.audit_ignore_outside_root is off — or nil
     # without Rails, where there is no app to be outside of.

data/lib/permittable/open_api.rb

@@ -373,7 +373,7 @@ module Permittable
         else
           free.each do |path, verb, template|
             holder = (paths[path] ||= {})
-            placed = with_path_parameters(operation, path)
+            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path)
             holder[verb] = template ? placed.merge("x-permittable-path" => template) : placed
             slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner, path)
           end
@@ -488,23 +488,93 @@ module Permittable
     # OpenAPI 3.1 requires every variable in a path template to be declared as
     # a path parameter — a document templating {id} without declaring it is
     # invalid, which every member route produced. The route set does not say
-    # what an :id is and the exporter does not guess: a path segment arrives as
-    # a string, so that is what it is documented as.
-    def with_path_parameters(operation, path)
-      variables = path.scan(/\{(\w+)\}/).flatten
+    # what an :id is, so a variable is a string unless the contract says
+    # otherwise: a rootless contract field named like one is that parameter's
+    # schema (path_fields), and leaves the body schema.
+    #
+    # `own` is the route's own spelling of the template, which differs
+    # from `path` when collapse_shapes placed the route under another
+    # route's spelling: the same shape, so the names pair up by position.
+    def with_path_parameters(operation, path, rule, own = path)
+      # A name the path templates twice (a mount and an engine route both
+      # name `:id`) is declared once: OpenAPI forbids two parameters with
+      # one name and location.
+      variables = path.scan(/\{(\w+)\}/).flatten.uniq
       return operation if variables.empty?
 
+      own_names = own.scan(/\{(\w+)\}/).flatten
+      fields = path_fields(rule, path.scan(/\{(\w+)\}/).flatten.zip(own_names).uniq(&:first))
       parameters = variables.map do |name|
-        { "name" => name, "in" => "path", "required" => true, "schema" => { "type" => "string" } }
+        schema = fields[name] ? path_schema(fields[name]) : { "type" => "string" }
+        { "name" => name, "in" => "path", "required" => true, "schema" => schema }
       end
       # Inserted ahead of requestBody, where a reader of the document expects
       # it; emission stays deterministic either way.
       operation.each_with_object({}) do |(key, value), out|
-        out["parameters"] = parameters if key == "requestBody"
-        out[key] = value
+        if key == "requestBody"
+          out["parameters"] = parameters
+          value = body_without(rule, fields.values, own_names)
+        end
+        out[key] = value unless value.nil?
       end
     end
 
+    # { path variable => the contract's field for it }. Rails merges the
+    # route's path parameters over the request's, so a field the route fills
+    # from the URL is read from the URL, never from the body: `id` in the
+    # body is overwritten, and a request that leaves it out is fine. A rooted
+    # contract reads its fields from inside the root, which a path parameter
+    # never reaches, so only a rootless one has such fields, and only at its
+    # top level. `names` pairs each variable of the placed path with the
+    # route's own name for it.
+    #
+    # Only a scalar field moves. A URL segment is one string, so an array or
+    # a hash can never be what it carries (`POST /defs/1,2` against
+    # `array :id` is a 422). Such a field stays in the body, where a client
+    # can at least say what it means.
+    def path_fields(rule, names)
+      return {} if rule[:root]
+
+      names.filter_map do |variable, own|
+        field = rule[:fields].find { |f| f[:name].to_s == own }
+        [variable, field] if field && field[:kind] == :scalar
+      end.to_h
+    end
+
+    # A moved field's schema as the path parameter documents it. The URL
+    # always supplies the segment, so a `default:` never applies and the
+    # value is never null: `nullable:` would only add "null" to the type.
+    def path_schema(field)
+      JsonSchema.field(field.except(:default, :nullable))
+    end
+
+    # The requestBody for `rule` without the fields a path parameter took
+    # over; nil, to leave it out, when that was every field. Such a body
+    # would be an empty object. An action declared with no fields at all
+    # keeps the empty body it always had.
+    #
+    # `unknown: :error` forbids every key the contract does not declare, but
+    # the runtime exempts the route's path parameters from that check and
+    # then overwrites them with the URL's values: `PATCH /widgets/7` with
+    # {"id":7,"name":"x"} is a 200 whether or not the contract declares `id`.
+    # That is the payload a Rails form, or a client sending a record back,
+    # produces, so the schema must not forbid it. Each name the route
+    # templates therefore stays in the body as an unconstrained property,
+    # any value and never required, since the value is read from the URL and
+    # nothing in the body can make the request wrong. A rooted contract
+    # needs none of this: its wrapper object is permissive already.
+    def body_without(rule, moved, templated)
+      rest = rule[:fields] - moved
+      return if rest.empty? && !moved.empty?
+
+      body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest))
+      return body unless rule[:unknown] == :error && !rule[:root]
+
+      properties = body["content"]["application/json"]["schema"]["properties"]
+      templated.each { |name| properties[name] ||= {} }
+      body
+    end
+
     # Drops every descriptor for a verb and concrete path that an earlier,
     # unconstrained route already answers (rails_routes calls it last).
     # Journey sorts the routes matching a request by precedence, their
@@ -533,10 +603,13 @@ module Permittable
     #
     # Descriptors arrive in route order (then verb, then optional variant),
     # so the first one seen is the first route. Precedence is a property of
-    # ONE route set, which is why this runs inside each rails_routes call and
-    # not in the readers: an engine's routes are relative to its mount point,
-    # and a list concatenated from an app's and an engine's must not let one
-    # shadow the other.
+    # ONE route table, which is why this runs once inside each rails_routes
+    # call and not in the readers: a list concatenated from an app's and an
+    # engine's must not let one shadow the other. An engine followed from its
+    # mount is part of that one table, expanded where the mount is drawn, so
+    # an app route ahead of the mount hides the engine's route for the same
+    # slot and an engine route hides a later app one (see rails_routes). An
+    # engine route is unconditional only when its mount is as well.
     #
     # Two more limits, both towards listing more. Only identical templates
     # are compared, so templates that differ at all, even only in a
@@ -616,9 +689,77 @@ module Permittable
     # A verb on a path that an earlier, unconstrained route already answers
     # is left out: Rails never dispatches it to the later route (see
     # drop_shadowed).
-    def rails_routes(app)
-      descriptors = app.routes.routes.each_with_index.flat_map do |route, index|
+    #
+    # A mounted Rails engine is part of the application: `mount Billing::Engine
+    # => "/billing"` makes every route the engine draws a URL of the app, so
+    # the audit's gate and the export must see them. With `engines: true`
+    # (the default) each such mount is followed into the engine's own route
+    # set, and the mount's path is put in front of every path found there,
+    # token by token, so a mount under `scope "(:locale)"`, one at a
+    # dynamic `at: ":tenant"` and one at "/" expand and join exactly as an
+    # app route would. A route reached through a mount carries its position
+    # as an Array, `[mount, route]` (`[3, 0, 5]` through an engine mounted in
+    # an engine), where an app route carries a bare Integer; so one engine
+    # mounted twice is two routes to its actions, as it is to a client. Only
+    # a Rails engine is followed: a Sidekiq::Web or a proc has no route set
+    # of ours to read and is skipped, as it always was. `engines: false`
+    # reads the one route set alone, for a caller that concatenates the lists
+    # of an app and its engines itself.
+    #
+    # Rails tries the routes in order with a mount standing where it is
+    # drawn, so the engine's routes are judged in that one order with the
+    # app's (see drop_shadowed): an app route ahead of the mount answers
+    # before the engine is asked, an engine route that matches answers and
+    # leaves an app route behind the mount unreached, and only a request the
+    # engine has no route for goes on (X-Cascade). A mount's `via:` limits
+    # the verbs it hands over: another verb is passed on, never answered by
+    # the engine.
+    #
+    # A parameter the mount and an engine route both name (`/{id}/.../{id}`)
+    # is not renamed: the template names it twice, the operation declares it
+    # once, and the README says so.
+    def rails_routes(app, engines: true)
+      drop_shadowed(collect_routes(app.routes, engines: engines, prefixes: [Prefix.new([], [])], parents: [],
+                                               visiting: [].freeze, reachable: true))
+    end
+
+    # What a route set mounted at one variant of its mount's path is led by.
+    # `tokens` are the mount's path from the root (see join_paths).
+    # `shadowed_by` are the paths of the variants Rails tries first, which
+    # leave this one nothing that they accept: a mount at "/" under
+    # `scope "(:locale)"` is matched as `/{locale}` before it is matched as
+    # "/", so /posts is the locale "posts" asking for the engine's root, and
+    # the engine's own /posts is not reached through the second variant. The
+    # mount's path is matched as a whole, unanchored and with no way back
+    # into it once the engine has been asked, so a variant that fits the
+    # leading segments of a path takes it whether or not the engine has a
+    # route for the rest.
+    Prefix = Struct.new(:tokens, :shadowed_by)
+
+    # The descriptors of one route set (`set`, anything with `routes`), each
+    # path led by every one of `prefixes` (a Prefix for each variant of the
+    # mounts above it, one empty one at the top) and each `route:` led by
+    # `parents`. `reachable` is whether every mount above answers every
+    # request for its path (see unconditional?); a route behind one that
+    # does not may be passed over, so it hides nothing. `visiting` is the
+    # route sets above this one, so an engine that mounts itself, or an app
+    # and engine that mount each other, ends the walk instead of recursing
+    # for good. Rails would loop on such a request too; the audit must not
+    # hang on it.
+    #
+    # The descriptors still carry `unconditional:`; the caller runs
+    # drop_shadowed over the whole list, mounts expanded in place.
+    def collect_routes(set, engines:, prefixes:, parents:, visiting:, reachable:)
+      visiting += [set]
+      set.routes.each_with_index.flat_map do |route, index|
+        id = parents.empty? ? index : parents + [index]
         requirements = route.requirements
+        if engines && (mounted = mounted_routes(route)) && visiting.none? { |above| above.equal?(mounted) }
+          found = collect_routes(mounted, engines: engines, prefixes: mount_prefixes(prefixes, route), parents: Array(id),
+                                          visiting: visiting, reachable: reachable && unconditional?(route))
+          verbs = route.verb.to_s.downcase.split("|")
+          next verbs.empty? ? found : found.select { |descriptor| verbs.include?(descriptor[:verb]) }
+        end
         verb = route.verb.to_s
         next [] if requirements[:controller].nil? || requirements[:action].nil?
 
@@ -627,9 +768,9 @@ module Permittable
         # audit entirely. Expand it into the verbs it actually answers.
         verb = ALL_VERBS if verb.empty?
 
-        variants = optional_variants(route.path.spec, requirements)
+        variants = optional_variants(route.path.spec, requirements, prefixes)
         # Read once per route; drop_shadowed reads it, then strips it.
-        unconditional = unconditional?(route)
+        unconditional = reachable && unconditional?(route)
         # One route can answer several verbs (`match via: [:patch, :put]`, and
         # the PATCH|PUT pair resources generates); documenting only the first
         # dropped the others from the export entirely. Verb by verb, then
@@ -638,12 +779,47 @@ module Permittable
         verb.split("|").flat_map do |single|
           variants.map do |path, shadows|
             descriptor = { controller: requirements[:controller], action: requirements[:action],
-                           verb: single.downcase, path: path, route: index, unconditional: unconditional }
+                           verb: single.downcase, path: path, route: id, unconditional: unconditional }
             shadows.empty? ? descriptor : descriptor.merge(shadows: shadows)
           end
         end
       end
-      drop_shadowed(descriptors)
+    end
+
+    # The Prefix of each variant of a mount's path under each of `prefixes`,
+    # outermost mount first, and within a mount present before absent, which
+    # is the order Rails' regexp tries them in. A variant is shadowed by every
+    # variant ahead of it: those of the same mount, and (through the
+    # `shadowed_by` it inherits) those of a mount above, judged where each
+    # was matched.
+    def mount_prefixes(prefixes, route)
+      own = variant_tokens(route.path.spec, route.requirements)
+      prefixes.flat_map do |above|
+        own.each_with_index.map do |tokens, index|
+          Prefix.new(join_paths(above.tokens, tokens),
+                     above.shadowed_by + own.take(index).map { |earlier| join_paths(above.tokens, earlier) })
+        end
+      end
+    end
+
+    # The route set a mount route hands requests to, or nil for any other
+    # route. Rails itself asks `route.app.engine?` (RoutesInspector does)
+    # and reads the set off `rack_app`. A route that cannot answer, such as a
+    # hand-built duck, is not a mount.
+    def mounted_routes(route)
+      return unless route.respond_to?(:app) && route.app.respond_to?(:engine?) && route.app.engine?
+
+      engine = route.app.rack_app
+      engine.routes if engine.respond_to?(:routes)
+    end
+
+    # `outer` then `inner`, as one path: the slash the mount ends in and the
+    # one the inner path starts with are one slash, and a route to the
+    # engine's root ("/") adds nothing to the mount's own path.
+    def join_paths(outer, inner)
+      inner = inner.drop(1) if outer.last == "/" && inner.first == "/"
+      inner = [] if inner == ["/"] && !outer.empty?
+      join_literals(outer + inner)
     end
 
     # A route parameter as optional_variants reads it: a `:name` segment or a
@@ -704,13 +880,23 @@ module Permittable
     # string: `to_s` prints an escaped parenthesis in a literal as a bare
     # one, which a string scan then read as a group. A Journey-shaped stand-in
     # may carry a String spec instead (string_variants).
-    def optional_variants(spec, requirements = {})
-      variants = if spec.respond_to?(:type)
-                   tree_variants(spec, requirements)
-                 else
-                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
-                 end
-      variants = variants.map { |tokens| join_literals(tokens) }
+    #
+    # `prefixes` are the Prefix of each variant of the mounts the route sits
+    # under (one empty one, none, by default). Each is put in front of every
+    # variant, the mount's variants outermost, which is the order Rails'
+    # regexp tries them in; a path a mount variant ahead of its own takes
+    # first is left out (see Prefix), and the shadowing above then judges the
+    # rest.
+    def optional_variants(spec, requirements = {}, prefixes = [Prefix.new([], [])])
+      # The route's own variants are judged before a mount's path is put in
+      # front of them: an empty one (`(:locale(/:region))` with nothing
+      # present) is no request path, but joined onto a mount it would read as
+      # the mount's own path, which Rails does not hand to that route.
+      own = variant_tokens(spec, requirements).select { |tokens| request_path?(tokens) }
+      variants = prefixes.flat_map do |prefix|
+        own.map { |tokens| join_paths(prefix.tokens, tokens) }
+           .reject { |joined| prefix.shadowed_by.any? { |earlier| shadowed?(earlier, joined.first(earlier.length)) } }
+      end
       # No group, no choice: nothing for one variant to shadow.
       return { render(variants.first) => [] } if variants.one?
 
@@ -732,6 +918,17 @@ module Permittable
       kept.to_a.reverse.to_h
     end
 
+    # The variants of a path spec, each a list of tokens with adjacent text
+    # joined (see join_literals), before any is dropped as shadowed.
+    def variant_tokens(spec, requirements)
+      variants = if spec.respond_to?(:type)
+                   tree_variants(spec, requirements)
+                 else
+                   string_variants(spec.to_s.sub(FORMAT_GROUP, ""), requirements).first
+                 end
+      variants.map { |tokens| join_literals(tokens) }
+    end
+
     # A Journey tree's variants, each a list of tokens: literal text and
     # Param. A group yields its contents' variants, then the empty one —
     # present before absent, as Rails' regexp tries them — except the

data/lib/permittable/tasks/audit.rake

@@ -11,12 +11,10 @@ namespace :permittable do
   task :audit, [:strict] => :environment do |_t, task_args|
     Rails.application.eager_load!
 
-    bases = []
-    bases << ActionController::Base if defined?(ActionController::Base)
-    bases << ActionController::API if defined?(ActionController::API)
     # Every controller, not just the ones including Permittable — a controller
-    # that never included it is unguarded, which is exactly the finding.
-    controllers = bases.flat_map(&:descendants).uniq.select(&:name)
+    # that never included it is unguarded, which is exactly the finding. Bare
+    # ActionController::Metal ones included; see Audit.rails_controllers.
+    controllers = Permittable::Audit.rails_controllers
     routes = Permittable::OpenAPI.rails_routes(Rails.application)
 
     entries = Permittable::Audit.entries(controllers: controllers, routes: routes)

data/lib/permittable/tasks/generate.rake

@@ -12,10 +12,7 @@ namespace :permittable do
   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)
+    controllers = Permittable::Audit.rails_controllers
 
     # { controller => actions to leave out of its draft }. A named controller
     # is drafted even if covered or ignored; the sweep skips both, and leaves

data/lib/permittable/tasks/openapi.rake

@@ -15,10 +15,7 @@ namespace :permittable do
   task :openapi, [:output] => :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 do |controller|
+    controllers = Permittable::Audit.rails_controllers.select do |controller|
       controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
     end
 

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.12.0".freeze
+  VERSION = "0.13.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport