permittable 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e135a1605d2d98e7c3a3952e2f9dc47394a656249f52d22b7018ed5dc15b23cb
-  data.tar.gz: f3748c6014a1f74099719fc8c42af289910c9f94d36687837cbe409fd67538a1
+  metadata.gz: be27cc7405432910133e85a3fb187c0147f14a7a28d98f960c58bc7190fc0271
+  data.tar.gz: e70282fd762f9a4c57d1b43e0c01b4306193997930b57015efc28b0af576564a
 SHA512:
-  metadata.gz: 12881e40e20e390c7eb93963a5ca89aa402ed58d79eb0bfa7383d7a2ea6c5b93f6d61d1b35c94ed27b3b75774ddc75256e1d176f9cea5470d06200f64aaecb7e
-  data.tar.gz: 312bd2b824147af2821dc318c0a66a250d65bd7626d80574e91a0bfb5cc06159a0e22428e30b6d463bfe57ece1fe72c56b4ca8b513b7cdbde1419eb637cd0533
+  metadata.gz: 61ec3dadad1f5fbc42c1c0403d228dff1d51c9ccaff13b8d455fb5d1ef795a01ddf7b64c0fa5e6dac76984bb22ad208b38ee50a1e6593326eb40704dbeecc8a6
+  data.tar.gz: '0443649c00422967f30d26d3e5982735433756c2aa1a669e26c10eaeaec707d48c2b4f2992805c3544e0bf68d502e0d9879776e78da2d497a7beacb18949dcb9'

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 <!-- CHANGELOG.md -->
 
+## 0.11.0 (2026-10-05)
+<!-- title: an audit ignore list, route-order-stable operationIds, and routes read the way Rails dispatches them -->
+
+One new setting and six fixes, closing every open issue. `Permittable.audit_ignore` lets `permittable:audit[strict]` pass in an app that uses ActiveStorage or a catch-all 404 route, and controllers from engines and gems are now listed apart from the app's own rather than counted against it. The OpenAPI export and the audit now read the route set the way Rails dispatches it: an earlier unconstrained route wins its verb and path over a later one (including a later `via: :all`), optional segments expand in Rails' own match order with constraints taken into account, and two routes no longer export paths that differ only in variable names. Colliding operationIds are ranked by the operation itself, so reordering `routes.rb` no longer renames a generated client method. The audit stops reporting a contract on a shared base controller as stale, and the wrapper-key exemption from 0.10.0 now holds whatever order ParamsWrapper and Permittable are included in, and no longer probes the request when no contract uses its answer. The compatibility matrix now runs the Railtie specs on every supported Rails line.
+
+Minor rather than patch: there is new public API, and three changes are visible from outside. Controllers whose source is outside `Rails.root` no longer count towards `[strict]` by default (set `Permittable.audit_ignore_outside_root = false` to keep counting them). Some existing operationIds change once on upgrade: see the operationId entry under **Changed** for which. And a route that an earlier unconstrained route already answers for the same verb and path is no longer described, so a contract left on its action is now reported as stale.
+
+### Added
+- **`Permittable.audit_ignore`: leave controllers and actions out of `permittable:audit` and `permittable:generate`.** Two endpoints failed `[strict]` in nearly every app without being a risk the app could fix: ActiveStorage's direct uploads controller (a POST with no contract, which `permittable:generate` also drafted), and a catch-all 404 route, whose `via: :all` reads as accepting a body on POST, PUT and PATCH. `Permittable.audit_ignore = ["active_storage/direct_uploads", "application#not_found"]` takes controller paths as Rails routes them and `controller#action` strings, validated on assignment: a class name raises with the path it meant, and a Class or a Regexp is refused. Controllers whose source is outside `Rails.root` (engines and gems: ActiveStorage, ActionMailbox, Devise, Rails' own `rails/*`) are ignored by default, including gems installed under the app's own `vendor/bundle`; `Permittable.audit_ignore_outside_root = false` audits them too. Ignored endpoints leave the counts and never fail `[strict]`, but the report still lists them in a section per reason, along with any ignore entry that matches no routed action. The generator's sweep skips ignored controllers and leaves an ignored action out of its draft; naming a controller still drafts it whole. (#69)
+
+### Changed
+- **Colliding operationIds are ranked by the operation itself, not by load and route order.** The rank is routed first, then controller path and action, then the shallowest path, then GET, POST, PATCH, PUT, DELETE. Reordering `routes.rb`, or a controller loading earlier, therefore never renames a generated client method. **This can change some existing operationIds once on upgrade**: two controllers that fold to one id (`admin/users` and `admin_users`) whose load order disagreed with string order, one action reached by separate routes at several paths or verbs (`post "admin/legacy"` before `post "legacy"`, `via: [:post, :get]`), and routes with nested optional groups. `resources` PATCH/PUT pairs, a single optional scope, and ids that never collided are unchanged. Adding or removing a colliding route can still rename the other members of its group. (#68)
+
+### Fixed
+- **The export and the audit described routes Rails never dispatches to.** A route that an earlier, unconstrained route already answers for the same verb and path is no longer described. A `match ..., via: :all` route keeps only the verbs no earlier route answers on that path, so `get "hooks"` → `index` drawn before it no longer produces a phantom `GET /hooks receive` audit row or hands that slot to `receive` in the export. A route hidden this way is dropped, and a contract left on its action is reported as stale. A constrained route (a segment requirement, a subdomain or host, a constraint object or lambda) never hides the routes behind it, because Rails passes on to them every request the constraint turns away: the audit is a gate, and it errs towards listing a route rather than hiding an unguarded one. Only identical path templates are compared. (#68)
+- **Optional route segments were expanded by string, not as Rails matches them, and two routes could export paths that differ only in variable names.** `scope "(:locale)"` put its root at `/{locale}` and its `get ":slug"` at `/{slug}`, two templates OpenAPI forbids side by side; and since Rails sends `GET /foo` to the root, the second never reached `pages#show` unless a constraint on `:locale` turned the request away. Such paths are now one path, spelled the way the route Rails tries first spells it: a later route under another verb is placed there with its own spelling in `x-permittable-path`, and one under the same verb is listed in the earlier operation's `x-permittable-shadows` instead of being emitted (its operation lands in `x-permittable-controllers` if it has no other path). Expansion now follows Rails' own match order, constraints included: `get "x(/:a)(/new)"` no longer documents `/x/new`, which Rails reads as `a = "new"` (unless `:a`'s constraint rejects it), and `x(/:a)(/:b)` with `a: /\d+/`, where Rails binds `/x/foo` to `:b`, lists `/x/{b}` on `/x/{a}` rather than dropping it silently. The route is read from the parsed Journey tree rather than its printed string, once per route rather than once per verb; a Journey-shaped stand-in with a String spec now honours escaped parentheses and raises on unbalanced ones instead of truncating the path. (#67)
+- **`Audit.stale` reported a contract inherited from a shared base controller as stale.** `permittable_contracts` is a `class_attribute`, so a base controller with no routes of its own, and every subclass routed to a different slice of its actions, was listed under "Contracts declared for actions no route reaches". A contract's action is now stale only when no controller that carries the contract (the declaring class or any of its subclasses) reaches it, and it is listed once, under the class that declared it. The audit summary also agrees in number when a count is one ("1 of those accepts a request body", "1 covered action declares no model:, so no schema-drift guard runs for it"). (#49)
+- **The wrapper-key exemption switched off when ParamsWrapper came before Permittable in the ancestor chain.** It recorded ParamsWrapper's key in `process_action`, relying on running before ParamsWrapper wrapped the body. A controller that includes `ActionController::ParamsWrapper` after Permittable, such as a Metal subclass, ran ParamsWrapper first, and every wrapped JSON request to a rootless `unknown: :error` contract was a 422 again. The key is now read in `process`, which every `process_action` runs inside, so module order no longer matters. The probe also no longer touches the request unless some contract on the controller acts on its answer: a rootless one that checks unknown keys or declares a field of the wrapper's name. (#70)
+
+### Test suite
+- **The compatibility matrix never ran the Railtie specs.** None of the `gemfiles/activesupport_*.gemfile` variants bundled `railties`, so `spec/railtie_spec.rb` skipped itself in every job but the root `Gemfile`'s: the `filter_parameters` wiring, its reach into ActiveRecord's `filter_attributes`, the late-bound registry and rake-task loading went untested on every supported Rails line but the newest. Each gemfile now pins `railties` to its own line, and the root `Gemfile`'s floor moves to 6.1 alongside `actionpack`/`activerecord`. Running the spec on old Rails surfaced two problems in its probe app, none in the gem: the probe booted without loading `logger` first (a NameError on activesupport 6.1), and asserted `precompile_filter_parameters`, which arrived in Rails 7.1. The gem itself needed no change on any version. (#50)
+- **The conformance spec read exported patterns as Ruby regexps, so `^` and `$` anchored a line.** `spec/support/tiny_json_schema.rb` compiled each `pattern` with `Regexp.new`, but the document holds ECMA-262, where `^` and `$` without the m flag anchor the whole input. `format: /\Aabc\z/` exports `^abc$`; the server and every real validator reject `"abc\n"` against it, and the instrument accepted it — a spurious "schema looser than server" divergence in the one direction the spec says cannot happen, which also hid a real anchor regression. The instrument now undoes the anchor translation before compiling (`^` → `\A`, `$` → `\z`), tokenizing escape pairs and character classes as units the way `EcmaPattern` does, and `spec/ecma_pattern_spec.rb` checks it against node over every exported pattern. No gem behaviour changes. (#48)
+
 ## 0.10.0 (2026-09-30)
 <!-- title: canonical numeric strings, the app's own CSRF param, and defaults that agree with requests -->
 

data/README.md

@@ -195,7 +195,7 @@ Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live
 - **[Adopting on a live API](#adopting-on-a-live-api)**
   - [Monitor mode](#monitor-mode-roll-out-without-rejecting)
   - [Generating draft contracts](#generating-draft-contracts-permittablegenerate)
-  - [Auditing coverage](#auditing-coverage-permittableaudit)
+  - [Auditing coverage](#auditing-coverage-permittableaudit) · [Ignoring controllers and actions](#ignoring-controllers-and-actions)
 - **[Beyond the controller](#beyond-the-controller)**
   - [Testing contracts](#testing-contracts-rspec-matchers)
   - [Standalone contracts](#standalone-contracts-no-controller)
@@ -832,6 +832,8 @@ bin/rails permittable:generate                      # every controller without a
 bin/rails "permittable:generate[UsersController]"   # one controller, even if covered
 ```
 
+The sweep skips what the audit [ignores](#ignoring-controllers-and-actions): controllers whose source is outside `Rails.root` (so ActiveStorage's direct uploads controller is not drafted), and anything in `Permittable.audit_ignore`. A `controller#action` entry leaves only that action out of the controller's draft. Naming a controller drafts it regardless, the same way it drafts a covered one.
+
 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(...)` and `params.expect(...)` calls (permitted keys give the field list and the `root:`), and prints a paste-ready draft:
 
 ```ruby
@@ -921,9 +923,9 @@ Three things it tells you that nothing else does:
 
 - **Which write actions are unguarded.** A `GET` without a contract is usually fine; a `POST` without one is untrusted input reaching the action unchecked. That count is the number `[strict]` fails on, which makes the task a CI gate: *no new unguarded write endpoint*.
 - **Which contracts aren't enforcing yet.** The audit runs inside the app, so unlike the exported OpenAPI it resolves the **effective** mode — a rule's own `mode:` first, then your app-wide `Permittable.mode`. This is the [monitor-mode](#monitor-mode-roll-out-without-rejecting) rollout dashboard.
-- **Which contracts have gone stale.** A contract declared for an action no route reaches, or for a routed action Rails would 404, is a renamed or deleted action that left its contract behind.
+- **Which contracts have gone stale.** A contract declared for an action no route reaches, or for a routed action Rails would 404, is a renamed or deleted action that left its contract behind. A contract on a shared base controller is stale only when no controller that inherits it reaches the action, and it is listed once, under the class that declares it.
 
-A route that lists several verbs is audited once per verb. A `match ... via: :all` route is expanded into exactly GET, POST, PUT, PATCH and DELETE, and listed once for each. `resources` routes all seven actions whether or not they exist. A route that Rails would 404 reads `action not found`: no method (inherited ones count), no `action_missing`, and no template to render implicitly. It is not counted against `[strict]` or as coverage. It stays in the table rather than disappearing. The template check uses the class-level view paths and the default lookup details. So a template that is only found at request time reads `action not found`, for example one behind a `prepend_view_path` in a `before_action`, or one that exists only as a variant.
+A route that lists several verbs is audited once per verb. A `match ... via: :all` route is expanded into exactly GET, POST, PUT, PATCH and DELETE, and listed once for each. Rails sends a request to the first route that matches its path and verb, and the audit lists what Rails dispatches. With `get "hooks", to: "webhooks#index"` before `match "hooks", to: "webhooks#receive", via: :all`, `GET /hooks` is listed under `index` only, and `receive` gets the other four verbs. Turn the two around and the `get` route is never reached, so it is not listed, and a contract on `index` shows as stale. The same rule removes a route declared twice, and the OpenAPI export applies it too. Only an unconstrained route hides the routes behind it, and only on the identical path. A route with a constraint can pass a request on: a segment requirement (`id: /\d+/`), a subdomain or host, or a constraint object or lambda. So the routes after it stay listed, even when the constraint happens to admit every request. With `constraints(AdminConstraint) { post "settings", ... }` ahead of `post "settings", to: "settings#update"`, every non-admin `POST` reaches `settings#update`, so its row stays and `[strict]` still counts it. The audit errs towards an extra row rather than a hidden route. Paths that differ at all, even only in a variable's name (`users/:id` and `users/:slug`), are both listed. `resources` routes all seven actions whether or not they exist. A route that Rails would 404 reads `action not found`: no method (inherited ones count), no `action_missing`, and no template to render implicitly. It is not counted against `[strict]` or as coverage. It stays in the table rather than disappearing. The template check uses the class-level view paths and the default lookup details. So a template that is only found at request time reads `action not found`, for example one behind a `prepend_view_path` in a `before_action`, or one that exists only as a variant.
 
 A catch-all 404 route (`match "*path", to: "application#not_found", via: :all`) shows its POST, PUT and PATCH rows as accepting a body. They do accept one: every stray body reaches the controller. Route only GET to the controller (Rails answers HEAD from it). Send the other verbs to a plain Rack endpoint, which never parses the body and which the audit does not list:
 
@@ -934,11 +936,60 @@ match "*path", to: ->(_env) { [404, { "content-type" => "text/plain" }, ["Not Fo
 
 A `config.exceptions_app = routes` setup (`match "/404", to: "errors#not_found", via: :all`) shows the same rows. It needs only `via: :get`, because on 6.1 and later `ShowExceptions` re-dispatches the error request as a GET.
 
-Under `[strict]` the task aborts on these rows, so the only choices today are to route the catch-all GET-only, as above, or to run the audit without `[strict]` until the ignore list ([#69](https://github.com/VSN2015/permittable/issues/69)) lands. 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.
+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.
 
-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.
+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).
+
+#### Ignoring controllers and actions
+
+Some routed endpoints are not yours to guard. Two are common enough to fail almost every `[strict]` run: ActiveStorage's direct uploads controller (a `POST` with no contract), and the catch-all 404 above, whose `via: :all` adds `POST`, `PUT` and `PATCH` rows. List them in an initializer:
+
+```ruby
+# config/initializers/permittable.rb
+Permittable.audit_ignore = [
+  "active_storage/direct_uploads", # every action of the controller
+  "application#not_found"          # one action, on every verb it is routed on
+]
+```
+
+An entry is a controller path the way Rails routes it (the controller half of `bin/rails routes`, such as `admin/users`), or `controller#action`. Entries must be strings, checked when you assign the list:
+
+- A class name raises `ArgumentError` naming the path you meant: `"ActiveStorage::DirectUploadsController"` → did you mean `"active_storage/direct_uploads"`?
+- A class raises too. Naming one in an initializer would autoload the controller during boot, which Zeitwerk refuses for a reloadable controller.
+- A `Regexp` raises. A pattern would also ignore controllers added after it, and catching a new unguarded endpoint is the point of the gate.
+
+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:
+
+```ruby
+Permittable.audit_ignore_outside_root = false
+```
+
+That default already covers ActiveStorage. Naming it, as above, keeps it ignored if you turn the default off. To put a gem's endpoint under the gate, subclass its controller in `app/controllers` (for Devise, `devise_for :users, controllers: { sessions: "users/sessions" }`). The subclass is the app's, so it is audited.
+
+Ignored endpoints leave the counts and never fail `[strict]`, but they stay in the report. Each reason gets its own section, with one line per action and the verbs it is routed on. An entry that matches no routed action (a typo, or a route since removed) is listed as well. Otherwise a typo would ignore nothing, and nothing would say so. With the initializer above plus a mistyped `"admin/report"`, the end of the report reads:
+
+```
+Ignored by Permittable.audit_ignore (left out of the counts above):
+  active_storage/direct_uploads#create  POST
+  application#not_found                 DELETE, GET, PATCH, POST, PUT
+
+Ignored as outside the app root (set Permittable.audit_ignore_outside_root = false to audit them):
+  active_storage/blobs/redirect#show  GET
+  active_storage/disk#show            GET
+  active_storage/disk#update          PUT
+  rails/health#show                   GET
+
+Permittable.audit_ignore entries that match no routed action (a typo, or a route since removed?):
+  admin/report
+```
+
+An unmatched entry is reported, not failed: a mistyped `application#not_foud` leaves the catch-all's rows in the count, so `[strict]` fails on those, and this list says why.
+
+`permittable:generate` honours the same list (see [generating draft contracts](#generating-draft-contracts-permittablegenerate)).
 
 ---
 
@@ -1037,7 +1088,7 @@ bin/rails permittable:openapi                       # JSON to stdout
 bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
 ```
 
-The task eager-loads the app (also exercising the drift guard), collects every controller with contracts, and maps documented actions onto `paths` via the route set. `OPENAPI_TITLE` / `OPENAPI_VERSION` override the `info` block. Pipe the output through Swagger UI, Redoc, Postman, or [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) and your frontend gets compile-time types for every request body.
+The task eager-loads the app (also exercising the drift guard), collects every controller with contracts, and maps documented actions onto `paths` via the route set. Each path and verb is documented under the action Rails dispatches it to, which is the first route that matches. So an explicit `get` before a `via: :all` route on the same path keeps `GET`, and a route behind an earlier, unconstrained one with the same path and verb is not documented under that verb. A constrained route hides nothing ([the audit](#auditing-coverage-permittableaudit) explains why). When two routes then claim one path and verb, the second operation lands under `x-permittable-controllers`. `OPENAPI_TITLE` / `OPENAPI_VERSION` override the `info` block. Pipe the output through Swagger UI, Redoc, Postman, or [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) and your frontend gets compile-time types for every request body.
 
 Or build fragments programmatically — no Rails required:
 
@@ -1050,7 +1101,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`; 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 — 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`; 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.
+
+**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"`. 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}`.
 
 **Every `operationId` is unique across the document, and only a collision is ever renamed.** An operation's id is its controller path with `/` folded to `_`, then its action: `users_create`, `admin_users_index`. Client generators name a method after the id, so the scheme itself never changes. Where two places in the document would carry one id, the exporter renames all but one of them:
 
@@ -1059,10 +1112,14 @@ Every operation references shared components for the [error envelope](#violation
 | One operation under two verbs (the separate PATCH and PUT routes `resources` draws to `update`, or one `match ..., via: [:patch, :put]` route) | `users_update` on PATCH, `users_update_put` on PUT |
 | The pair again at a second path (`resources :orgs { resources :users }`) | `users_update_2` on the second PATCH, `users_update_3` on the second PUT |
 | One operation under every verb (with `via: :all` routes, which the exporter documents under each verb) | `webhooks_receive` on GET, then `webhooks_receive_post`, `_put`, `_patch`, `_delete` |
-| One operation at two paths under one verb (with the optional-segment expansion: `(/:locale)/posts` is documented at `/posts` and `/{locale}/posts`) | `posts_create` on the first path in route order, `posts_create_2` on the other |
-| Two controllers that fold to one id (`admin/users` and `admin_users`, both GET) | `admin_users_index` on the first controller, `admin_users_index_2` on the second |
+| One operation at two paths under one verb (with the optional-segment expansion: `(/:locale)/posts` is documented at `/posts` and `/{locale}/posts`) | `posts_create` on the shallower path, `posts_create_2` on the other |
+| Two controllers that fold to one id (`admin/users` and `admin_users`, both GET) | `admin_users_index` on `admin/users`, whose controller path sorts first, and `admin_users_index_2` on `admin_users` |
+
+One place keeps the plain id. The exporter ranks the places by what they are, never by the order it finds them in. A routed operation comes before one under `x-permittable-controllers`, which takes part because it is in the same document. Then operations are ranked by controller path, then action, compared as strings, whatever their verbs. Within one operation, the shallowest path comes first (the fewest segments, then alphabetical order), then the verb: GET, POST, PATCH, PUT, DELETE. So PATCH comes before PUT whichever the route lists first, and `match via: [:put, :patch]` and `resources` name the PATCH method the same way. Every other place gets its verb appended when that verb differs from the plain id's verb and the result is free. Otherwise it gets the next free number in rank order, from `_2`. So a second PATCH is `users_update_2`, not `users_update_patch`, and a second POST is `posts_create_2`. A route declared twice is placed once, and a controller passed twice is documented once, so neither collides with itself.
+
+**The stability rules.** An id that only one operation would carry never changes, even when a suffix elsewhere would spell it; that suffix is numbered instead. Reordering `routes.rb`, or a controller that loads earlier, renames nothing, because the rank never reads that order. (The exception is two routes that answer the same path and verb. Their order decides which one Rails dispatches to, and the export follows Rails. When the first of them is constrained, both are kept, controller order picks which operation takes the slot, and the other lands under `x-permittable-controllers`.)
 
-One place keeps the plain id. A routed operation comes before one under `x-permittable-controllers`, which takes part because it is in the same document. After that, controller, action and route order decide. Within one operation, PATCH comes before PUT whichever the route lists first, so `match via: [:put, :patch]` and `resources` name the PATCH method the same way. Between two operations only the order counts, whatever the verbs. Every other place gets its verb appended when that verb differs from the plain id's verb and the result is free. Otherwise it gets the next free number, from `_2`. So a second PATCH is `users_update_2`, not `users_update_patch`, and a second POST is `posts_create_2`. **The stability rule:** an id that only one operation would carry never changes, even when a suffix elsewhere would spell it; that suffix is numbered instead. So a change to routes or controllers can rename only operations that collide, never one that stands alone. A route declared twice is placed once, and a controller passed twice is documented once, so neither collides with itself.
+**What can still rename a generated method: a change to a colliding group.** No scheme can keep every id when a new collider arrives, because one of them must take a suffix. A new route, action or controller whose id collides gets a suffix. If it ranks first, it takes the plain id from the place that had it instead. Every numbered place ranked after it moves along by one. Removing or renaming a collider moves the others the same way. Only the members of the colliding group can be renamed, never an id that stands alone. If a client must never change, remove the collision: give the operations distinct controller paths or action names.
 
 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.
 
@@ -1144,12 +1201,14 @@ A `format:` regexp that does not translate to ECMA-262 is looser in the same way
 | `Permittable.error_format` / `=` | `:envelope` (default) or `:problem` — see [RFC 9457 problem+json](#rfc-9457-problemjson) |
 | `Permittable.problem_base_uri` / `=` | Base URI for problem `type` members |
 | `Permittable.check_column_types` / `=` | Opt in to the [type half of the drift guard](#checking-types-too-opt-in) (default `false`) |
+| `Permittable.audit_ignore` / `=` | Controller paths and `controller#action` strings the audit and the generator [leave out](#ignoring-controllers-and-actions) (default `[]`) |
+| `Permittable.audit_ignore_outside_root` / `=` | Also leave out controllers whose source is outside `Rails.root` (default `true`) |
 | `Permittable.fields(&block)` | A reusable [field group](#reusing-fields-permittablefields-and-use) — splice it into a contract with `use` |
 | `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::Audit` | Coverage across the route set (`.entries`, `.summary`, `.stale`, `.format`) — see [auditing coverage](#auditing-coverage-permittableaudit) |
+| `Permittable::Generator` | Contract drafting (`.draft`, `.for_controller`, `.scan`, `.targets`) — see [generating draft contracts](#generating-draft-contracts-permittablegenerate) |
+| `Permittable::Audit` | Coverage across the route set (`.entries`, `.summary`, `.stale`, `.format`, `.ignore_reason`, `.unmatched_ignores`) — see [auditing coverage](#auditing-coverage-permittableaudit) |
 | `Permittable::Contract` | [Standalone contracts](#standalone-contracts-no-controller) (`.define`, `#call`, `#call!`, `#json_schema`, `#rule`, `#fields`) |
 | `Permittable::FieldGroup` | A [reusable field list](#reusing-fields-permittablefields-and-use) (`#fields`, `#names`) — built by `Permittable.fields` |
 | `Permittable::Matchers` | RSpec matchers via `require "permittable/rspec"` — `permit_param` for the declaration, `accept_params`/`reject_params` for the behaviour. See [testing contracts](#testing-contracts-rspec-matchers) |

data/lib/permittable/audit.rb

@@ -15,6 +15,11 @@ module Permittable
   #   bin/rails permittable:audit[strict]   # ...and exit 1 if a write action
   #                                         #    is unguarded (a CI gate)
   #
+  # What is not the app's to guard — ActiveStorage's direct uploads, a
+  # catch-all 404 — is left out with Permittable.audit_ignore, and every
+  # controller whose source is outside Rails.root is left out by default.
+  # Either way it leaves the counts and [strict], never the report.
+  #
   # Plain Ruby over the frozen registry and a list of route descriptors (the
   # same `{ controller:, action:, verb:, path: }` shape OpenAPI.rails_routes
   # produces, plus the optional `route:` it tags each one with), so it is
@@ -30,6 +35,14 @@ module Permittable
     # is usually fine; a POST without one is the finding.
     BODY_VERBS = %w[post put patch].freeze
 
+    # Why an entry is left out of the counts, keyed as Entry#ignored holds it,
+    # with the heading its section of the report carries. Listed in this
+    # order: what the app chose to ignore first, then what it got by default.
+    IGNORE_REASONS = {
+      configured: "Ignored by Permittable.audit_ignore (left out of the counts above):",
+      outside_root: "Ignored as outside the app root (set Permittable.audit_ignore_outside_root = false to audit them):"
+    }.freeze
+
     # One routed action, paired with the rule a request for it would resolve
     # through (nil when nothing covers it — including when the controller
     # never included the concern, which is exactly the case worth finding).
@@ -37,8 +50,10 @@ module Permittable
     # `missing_action` marks a route to an action the controller does not
     # define — see Audit.missing_action?. `route` identifies the route the
     # path came from (nil for a hand-built descriptor, which is then its own
-    # route); see `summary`.
-    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, keyword_init: true) do
+    # route); see `summary`. `ignored` is why the entry is left out of the
+    # counts — a key of IGNORE_REASONS — or nil when it is audited.
+    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, :ignored,
+                       keyword_init: true) do
       def covered?
         !rule.nil?
       end
@@ -47,6 +62,10 @@ module Permittable
         missing_action == true
       end
 
+      def ignored?
+        !ignored.nil?
+      end
+
       # The mode this action would actually run in, rule-level declaration
       # first and the app-wide default behind it.
       def mode
@@ -69,25 +88,137 @@ module Permittable
     # Every routed action of every given controller, sorted for stable output.
     # Pass ALL controllers, not just the ones including Permittable — a
     # controller that never included it is unguarded, which is the point.
-    def entries(controllers:, routes:)
+    #
+    # Ignored actions are returned too, marked with why (Entry#ignored):
+    # `ignore:` is the Permittable.audit_ignore list, and `root:` the app
+    # root a controller's source must be inside (see app_root; nil ignores
+    # nothing on that ground). Both default to the app's own configuration,
+    # as `mode` does.
+    def entries(controllers:, routes:, ignore: Permittable.audit_ignore, root: app_root)
       routes = routes.to_a
-      controllers.flat_map { |controller| controller_entries(controller, routes) }
+      controllers.flat_map { |controller| controller_entries(controller, routes, ignore: ignore, root: root) }
                  .sort_by { |entry| [entry.controller, entry.path, entry.verb.to_s] }
     end
 
-    def controller_entries(controller, routes)
+    # The app's own choice outranks the default: a controller that is both
+    # configured and outside the root is reported as configured, so its entry
+    # counts as matched (see unmatched_ignores) — the README's own example
+    # names ActiveStorage, which the default already covers. The location is
+    # looked up once per controller, not once per route.
+    def controller_entries(controller, routes, ignore: Permittable.audit_ignore, root: app_root)
       key = OpenAPI.controller_key(controller) || controller.inspect
       missing = missing_lookup(controller)
+      outside = :outside_root if outside_root?(controller, root)
       routes.select { |route| route[:controller].to_s == key }.map do |route|
         action = route[:action].to_s
         Entry.new(controller: key, action: action, verb: route[:verb], path: route[:path],
                   rule: rule_for(controller, action), missing_action: missing[action],
-                  route: route[:route])
+                  route: route[:route], ignored: configured_ignore(key, action, ignore) || outside)
+      end
+    end
+
+    # Why `controller` — or one of its actions — is left out of the audit and
+    # of permittable:generate: :configured (Permittable.audit_ignore names the
+    # controller, or "controller#action"), :outside_root, or nil. The
+    # generator asks per action; see Generator.targets.
+    def ignore_reason(controller, action = nil, ignore: Permittable.audit_ignore, root: app_root)
+      key = OpenAPI.controller_key(controller) || controller.inspect
+      configured_ignore(key, action, ignore) || (:outside_root if outside_root?(controller, root))
+    end
+
+    def configured_ignore(key, action, ignore)
+      :configured if ignore.include?(key) || (action && ignore.include?("#{key}##{action}"))
+    end
+
+    # The ignore entries no routed action answers to — a controller that is
+    # not routed, an action it does not route, or a typo of either. Ignored
+    # entries count as matches: the question is whether the entry names
+    # something, not whether it was the only reason that something was
+    # ignored.
+    def unmatched_ignores(entries, ignore: Permittable.audit_ignore)
+      ignore.reject do |item|
+        key, action = item.split("#", 2)
+        entries.any? { |entry| entry.controller == key && (action.nil? || entry.action == action) }
+      end
+    end
+
+    # The root a controller's source must be inside to be audited:
+    # Rails.root, unless Permittable.audit_ignore_outside_root is off — or nil
+    # without Rails, where there is no app to be outside of.
+    def app_root
+      return nil unless Permittable.audit_ignore_outside_root
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:root)
+
+      ::Rails.root&.to_s
+    end
+
+    # Whether `controller` is an engine's or a gem's rather than the app's:
+    # its source is outside `root`, or inside a directory gems are installed
+    # in — `bundle config path vendor/bundle`, which CI caches and Docker
+    # images commonly use, puts every gem inside the app's root, and
+    # ActiveStorage's controller is no more the app's for being there. A gem
+    # directory that holds the root itself (a GEM_HOME set to the app, or to
+    # a parent of it) says nothing about which side a file is on, so it is
+    # not consulted — otherwise every app controller would read as a gem's
+    # and [strict] would pass on nothing. A controller that cannot be located
+    # is audited: for a gate, a false alarm beats a missed endpoint.
+    def outside_root?(controller, root)
+      return false if root.nil?
+
+      path = source_path(controller)
+      return false if path.nil?
+
+      !within?(path, root) || Gem.path.any? { |dir| within?(path, dir) && !within?(root, dir) }
+    end
+
+    # Where `controller` is defined: its constant's own definition (the
+    # `class` line — reopening a gem's controller in app/ does not move it),
+    # or, for a class whose constant cannot be found, the first of its own
+    # methods that has a location. nil when neither says.
+    #
+    # A constant that is registered for autoload but not loaded reports the
+    # `autoload` call instead — never the case here, since only loaded
+    # classes have descendants to audit.
+    def source_path(controller)
+      name = controller.name if controller.respond_to?(:name)
+      located = begin
+        # [] for a constant defined in C, so `first` is nil there too.
+        Object.const_source_location(name)&.first if name.is_a?(String) && !name.empty?
+      rescue NameError
+        nil
+      end
+      located || method_source_path(controller)
+    end
+
+    def method_source_path(controller)
+      return nil unless controller.is_a?(Module)
+
+      methods = controller.instance_methods(false) + controller.private_instance_methods(false)
+      methods.lazy.filter_map { |name| controller.instance_method(name).source_location&.first }.first
+    end
+
+    # Whether `path` is `dir` or inside it, compared both as written and with
+    # symlinks resolved: Rails.root is a realpath, and on macOS a tmpdir under
+    # /var is really under /private/var — either side alone can disagree with
+    # the other, and an app controller misread as outside the root would drop
+    # out of [strict]. A form that cannot be resolved (a path that does not
+    # exist) is compared as written only.
+    def within?(path, dir)
+      [[File.expand_path(path), File.expand_path(dir)], [realpath(path), realpath(dir)]].any? do |file, base|
+        file && base && (file == base || file.start_with?(File.join(base, "")))
       end
     end
 
+    def realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    end
+
     # action => missing?, answered once per action: a `via: :all` route is
-    # five entries for one action, and each resolver call builds a controller.
+    # up to five entries for one action (fewer when an earlier, unconstrained
+    # route already answers some of its verbs on that path, see
+    # OpenAPI.drop_shadowed), and each resolver call builds a controller.
     # The action list is read once per controller, not once per route.
     def missing_lookup(controller)
       listed = listed_actions(controller)
@@ -144,20 +275,64 @@ module Permittable
     # kind is in no summary bucket, so without this it would vanish from the
     # report's conclusions. Catch-all rules declare no actions, so they never
     # appear here.
+    #
+    # Judged per RULE, not per class: permittable_contracts is a
+    # class_attribute, so a subclass carries every rule its parent declared,
+    # and judging each class alone listed a shared base (routed to nothing)
+    # and every subclass routed to a different slice of its actions. A rule's
+    # action is stale only when NO controller carrying that rule reaches it —
+    # the class that declared it, or any descendant among `controllers:` — and
+    # it is listed once, under the declaring class, where the fix is made.
+    # Counting only the rules a class added itself would not do: the shared
+    # base still has no routes. Shadowing is not judged: an action some
+    # carrier reaches is not stale, even if that carrier declares its own rule
+    # for it, just as a rule redeclared within one class never was.
     def stale(controllers:, routes:)
       routes = routes.to_a
-      controllers.each_with_object({}) do |controller, found|
+      reaches = Hash.new { |memo, controller| memo[controller] = reach_lookup(controller, routes) }
+      carriers(controllers).each_with_object({}) do |(rule, held_by), found|
+        declarer = declaring_class(held_by.first, rule)
+        holders = held_by | [declarer]
+        left = rule[:actions].reject { |action| holders.any? { |controller| reaches[controller][action] } }
+        next if left.empty?
+
+        key = OpenAPI.controller_key(declarer) || declarer.inspect
+        found[key] = (found.fetch(key, []) + left).uniq
+      end
+    end
+
+    # rule => the given controllers carrying it, in first-seen order. Keyed by
+    # IDENTITY: permit_params hands a subclass its parent's rule objects, while
+    # two classes declaring the same fields build equal but distinct rules.
+    def carriers(controllers)
+      controllers.each_with_object({}.compare_by_identity) do |controller, held|
         next unless controller.respond_to?(:permittable_contracts)
 
-        key = OpenAPI.controller_key(controller) || controller.inspect
-        routed = routes.select { |route| route[:controller].to_s == key }.map { |route| route[:action].to_s }
-        declared = controller.permittable_contracts.flat_map { |rule| rule[:actions] }.uniq
-        missing = missing_lookup(controller)
-        left = declared.select { |action| !routed.include?(action) || missing[action] }
-        found[key] = left unless left.empty?
+        controller.permittable_contracts.each { |rule| (held[rule] ||= []) << controller }
       end
     end
 
+    # action => whether a request for it reaches `controller`: routed there,
+    # and not to an action Rails would 404. Lazy, so the resolver is asked
+    # only about actions some contract declares.
+    def reach_lookup(controller, routes)
+      key = OpenAPI.controller_key(controller) || controller.inspect
+      routed = routes.select { |route| route[:controller].to_s == key }.to_set { |route| route[:action].to_s }
+      missing = missing_lookup(controller)
+      Hash.new { |memo, action| memo[action] = routed.include?(action) && !missing[action] }
+    end
+
+    # The highest ancestor still carrying `rule` — the class whose
+    # permit_params declared it, whether or not it was among `controllers:`.
+    def declaring_class(controller, rule)
+      controller = controller.superclass while controller.respond_to?(:superclass) && carries?(controller.superclass, rule)
+      controller
+    end
+
+    def carries?(controller, rule)
+      controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any? { |held| held.equal?(rule) }
+    end
+
     # The numbers worth putting in a CI log. `uncovered_with_body` is the one
     # that should be zero; `unguarded_models` counts covered actions whose
     # rule declares no `model:`, so no schema-drift guard runs for them.
@@ -172,8 +347,11 @@ module Permittable
     # An action the controller does not define takes no body, and a contract
     # left on one guards nothing, so it is counted as `missing_actions` and in
     # no other bucket — the buckets stay disjoint and still add up to `actions`.
+    #
+    # An ignored entry (Entry#ignored) is in none of the counts, so it never
+    # fails [strict]; `format` lists it in a section of its own instead.
     def summary(entries)
-      entries = routed(entries)
+      entries = routed(entries.reject(&:ignored?))
       found, missing = entries.partition { |e| !e.missing_action? }
       {
         actions: entries.length,
@@ -196,13 +374,19 @@ module Permittable
     end
 
     # The human-readable report: one block per controller, then the summary,
-    # then anything stale.
-    def format(entries, stale: {})
+    # then anything stale. The table and the summary cover the audited
+    # entries; what was ignored follows in sections of its own, then any
+    # ignore entry that matched nothing — `unmatched` defaults to checking
+    # Permittable.audit_ignore, the list `entries` defaults to.
+    def format(entries, stale: {}, unmatched: unmatched_ignores(entries))
       return "Permittable audit: no routed actions to report.\n" if entries.empty?
 
+      ignored, entries = entries.partition(&:ignored?)
       out = entries.group_by(&:controller).map { |key, group| controller_block(key, group) }
       out << summary_lines(summary(entries), rows: entries.length)
       out << stale_lines(stale) unless stale.empty?
+      out << ignored_lines(ignored) unless ignored.empty?
+      out << unmatched_lines(unmatched) unless unmatched.empty?
       "#{out.join("\n")}\n"
     end
 
@@ -242,9 +426,14 @@ module Permittable
     # say WHY they differ: an optional segment's variants are the usual
     # reason, but two concatenated route lists sharing a controller, action
     # and index collapse the same way.
+    #
+    # Each line agrees with its own count: "1 of those accepts", "1 covered
+    # action declares ... for it". `rows` needs no singular — it only prints
+    # when it exceeds the route count, so it is at least 2.
     def summary_lines(counts, rows: counts[:actions])
       body = counts[:uncovered_with_body]
       missing = counts[:missing_actions]
+      models = counts[:unguarded_models]
       # Its own bucket, so the head line still adds up to the route count.
       not_found = ", #{missing} not found (Rails 404s #{missing == 1 ? 'it' : 'them'})" unless missing.zero?
       listed = " in #{rows} rows" unless rows == counts[:actions]
@@ -253,9 +442,10 @@ module Permittable
         "#{counts[:actions]} routed action#{'s' unless counts[:actions] == 1}#{listed}: " \
         "#{counts[:enforced]} enforced, #{counts[:monitored]} in monitor mode, " \
         "#{counts[:uncovered]} without a contract#{not_found}",
-        "  #{body} of those accept a request body#{' — untrusted input reaches the action unchecked' unless body.zero?}",
-        "  #{counts[:unguarded_models]} covered action#{'s' unless counts[:unguarded_models] == 1} " \
-        "declare no model:, so no schema-drift guard runs for them"
+        "  #{body} of those accept#{'s' if body == 1} a request body" \
+        "#{' — untrusted input reaches the action unchecked' unless body.zero?}",
+        "  #{models} covered action#{models == 1 ? ' declares' : 's declare'} no model:, " \
+        "so no schema-drift guard runs for #{models == 1 ? 'it' : 'them'}"
       ].join("\n")
     end
 
@@ -264,5 +454,26 @@ module Permittable
       "\nContracts declared for actions no route reaches or Rails would 404 (renamed or deleted?):\n" \
         "#{pairs.map { |pair| "  #{pair}" }.join("\n")}"
     end
+
+    # One section per reason, in IGNORE_REASONS order, and one line per
+    # controller#action with every verb it is routed on: a `via: :all`
+    # catch-all is one line rather than five rows, so what was left out stays
+    # visible without crowding the table it was left out of.
+    def ignored_lines(ignored)
+      IGNORE_REASONS.filter_map do |reason, heading|
+        group = ignored.select { |entry| entry.ignored == reason }
+        next if group.empty?
+
+        verbs = group.group_by { |entry| "#{entry.controller}##{entry.action}" }
+                     .transform_values { |list| list.map { |entry| entry.verb.to_s.upcase }.uniq.join(", ") }
+        width = verbs.keys.map(&:length).max
+        "\n#{heading}\n#{verbs.map { |pair, list| "  #{pair.ljust(width)}  #{list}" }.join("\n")}"
+      end.join("\n")
+    end
+
+    def unmatched_lines(unmatched)
+      "\nPermittable.audit_ignore entries that match no routed action (a typo, or a route since removed?):\n" \
+        "#{unmatched.map { |item| "  #{item}" }.join("\n")}"
+    end
   end
 end