coatepec 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e0e730ee65e046252297e502039ca8db8b17b4d1774564f79cb708dbe4500b2
-  data.tar.gz: 66d1afbd32ef8ba95de436e046d5b8b90452578a5a1ee0af2a442f7a14f0054d
+  metadata.gz: 550a60896b3c267b12b5db85b787c52d93b97dd2b95409c8bf78943ea63a27d0
+  data.tar.gz: '09c6cbbc7c00dd604d2cb5dfbabbb0101aea3cadf5d24070f3254a144bb45012'
 SHA512:
-  metadata.gz: b5168b16140e5199c41a11c4e9a73efee643d2acf80405090a7b1ff0ba32ab94432b1e02b396ca5456ba879960025ef640434fcc265ca19147633e00d0b47a88
-  data.tar.gz: 209b126ecc16dadfacad123098e06bcb9d53649f7f3a8b2eca7555a6d098d35f7307cc81b38b015ea0891b49ef088bbe55c3f33ea2de243e14e0212322e68ded
+  metadata.gz: 484557dd0635d21f7669a12b6accab0684e4850e4ac91b6718b733bd23372aceaa5b903f387facb22fdc6b0c2d0a09dfb4805ace67e6b24c66f95c482240d69b
+  data.tar.gz: e3fcc83c1f752dfba27b1260584b2ee1d0df5707e36163d049015babe269290a2467b3018c0e3696d8d6c4d4fcaf5bf8b2e325a3792ac7d3bcb085cad433e73c

data/.rubocop.yml

@@ -15,6 +15,11 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
+Metrics/ParameterLists:
+  # Keyword-only signatures here mirror the MCP tools' input schemas, and a tool
+  # gaining an input shouldn't force a refactor; positional lists stay capped at 5.
+  CountKeywordArgs: false
+
 Metrics/BlockLength:
   # RSpec's describe/context/it DSL naturally produces long blocks; this is the
   # standard exclusion used by rubocop-rspec's own default config. inherit_mode

data/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## 0.8.0
+
+- Tool responses are now compact JSON rather than pretty-printed (22-32%
+  smaller on measured payloads); set `COATEPEC_PRETTY=1` on the server
+  process to restore indentation.
+- `rails_spec_run` now omits passing examples from `examples` by default --
+  a 49-test green run drops from ~3,700 tokens to ~160 -- and `summary` gains
+  `pending_count`. Pass the new `include_passing: true` input to get the full
+  roster back (still capped at 500 examples). `rails_spec_flaky_check` is
+  unaffected: it still sees every example.
+- `examples[].description` (and `flaky_examples[].description`) is omitted
+  when it would only repeat `id`, which is always the case for Minitest.
+- `rails_routes` (with `engines: "include"`) and `rails_controller` now
+  include the routes of engines mounted in the application, expanded one
+  level deep (an engine mounted inside another engine stays an opaque mount
+  route, the same boundary `bin/rails routes` draws). Paths carry the mount
+  point, so `/widget_admin/audits` is what both tools report, and a
+  controller living inside an engine no longer has all of its actions listed
+  under `unroutable_actions`.
+- `rails_routes` gains an `engine` column and `rails_controller`'s
+  `actions[].routes` entries an `engine` field: `null` for an application
+  route, the engine's class name otherwise. `rails_routes`' `query` matches
+  against it like every other column, so `query: "Avo::Engine"` with
+  `engines: "include"` or `"only"` returns exactly that engine's routes.
+  Application routes are listed before engine routes.
+- An engine route's `name` (`route_name` in `rails_controller`) is relative
+  to its engine: it is reached through the mount's helper,
+  `<mount name>.<name>_path`, where the mount name is the `name` of the mount
+  route itself -- never as a top-level url helper.
+- `rails_routes` and `rails_controller` now omit routes Rails marks
+  `internal` -- its own `/rails/info` and friends -- matching
+  `bin/rails routes`. This is a behaviour change for callers that relied on
+  seeing them.
+- Add Minitest support to `rails_spec_run` and `rails_spec_flaky_check`:
+  selectors under a `test/` root ending in `_test.rb` run through Rails'
+  Minitest runner in the same warm worker, with the same
+  `example`/`seed`/`fail_fast`/`timeout_seconds` inputs and the same result
+  shape (`id` is `ClassName#test_method`; a skip is `"pending"`, an error is
+  `"failed"`). The framework is chosen per call from the selector paths --
+  an app that has both `spec/` and `test/` works without configuration; one
+  call may not mix the two (`mixed_test_frameworks`).
+- The Minitest child sets `PARALLEL_WORKERS=1`, so a selection above Rails'
+  parallelization threshold runs serially under the call's single timeout
+  instead of forking a worker tree.
+- `file:LINE` selection is implemented by Coatepec itself rather than relying
+  on Rails' line filtering, which is absent in apps generated with
+  `--skip-test` and targets a method Minitest 6 no longer calls on Rails 7.1.
+- Path validation now runs before the framework is required, so an invalid
+  path on a Minitest-only app reports `invalid_spec_path` instead of
+  `unsupported_test_framework`. `invalid_spec_path` keeps its code for both
+  frameworks.
+- `rails_model` collapses validators with identical name, attributes and
+  options into one entry (a concern and the model body declaring the same
+  validation used to appear twice); the 200-item cap now counts distinct
+  validators.
+- `rails_routes` defaults to 100 routes per page (was 50 -- engine expansion
+  roughly doubled route counts when engines are included) and returns
+  `next_offset` for the follow-up call, `null` on the last page.
+- `rails_spec_run`: when several tests fail with the same error text (a
+  broken layout erroring every controller test, say), `stdout` keeps the
+  first failure block and replaces each repeat with one roll-up line
+  naming the other tests -- a 5-error controller run drops from ~4,850 B to
+  roughly a third of that. Backtrace frames and RSpec's `Failure/Error:`
+  source line are ignored when deciding that two blocks match.
+- `rails_spec_run` gains `include_stdout` (`failures`, the default; `always`;
+  `never`). A passing run's `stdout` is `null` by default -- its progress
+  dots and summary line only repeat `summary` -- and a failing run's is
+  returned; `always` and `never` override that either way. The key stays so
+  the result shape is uniform. `stderr` is always returned.
+- `rails_routes` returns application routes only by default and gains
+  `engines` to change that: `include` lists the routes of mounted engines
+  too -- the routes 0.8.0 added by expanding engines -- and `only` lists just
+  those; the default matches pre-0.8.0 output (application routes, the mount
+  route included). Every response carries `engines` (the filter applied) and
+  `engines_excluded` (how many routes matching `query` were withheld), so the
+  omission is stated, never silent. The filter applies after `query` and
+  before paging, so `matched` and `next_offset` describe the kept set; an
+  engine's mount route counts as an application route. Measured on an app
+  with a mounted admin engine, six typical route queries cost 57% less
+  context with engine routes withheld.
+- `rails_model` cuts an array-valued validator option longer than 20 entries
+  to its first 20 and adds `<option>_count` (the full length) and
+  `<option>_truncated: true` beside it -- a 249-code `inclusion` list no
+  longer costs 1.4 KB per model. Shorter lists are unchanged and carry no
+  sibling keys.
+- Every tool response's `meta` is now just `duration_ms`; `project_root` is
+  reported once by `rails_runtime_status` (beside `environment`) instead of
+  on every call.
+- `rails_spec_run` results carry `child_pid`, `signaled`, `termsig`,
+  `stopsig` and `coredump` only when the child did not exit normally (a
+  timeout kill or a crash); a normal run reports `status`, `exit_code` and
+  the output fields alongside the usual `summary` and `examples`.
+- `rails_model` returns `name`, `table_name`, `primary_key`, `abstract_class`
+  and `counts` (the size of each of its four lists, after validator
+  de-duplication and the 200-item caps) by default, and gains `fields`, an
+  array of `columns`/`associations`/`validators`/`enums` naming the lists to
+  include; omitted or `[]` means counts only. Callers that read the lists
+  must now ask for them -- the default response is roughly an order of
+  magnitude smaller than the full one on a typical model.
+- `rails_routes` returns `columns` (`name`, `verb`, `path`, `controller`,
+  `action`, `engine`) and `rows` instead of one object per route -- the six
+  key names were a third of every item's bytes -- and both `rails_routes`
+  and `rails_controller` report paths without the `(.:format)` suffix Rails
+  appends to most routes.
+- `rails_spec_run`'s `summary` gains `error_count` (how many of
+  `failure_count` were errors rather than assertion failures) and
+  `assertion_count` (Minitest's assertion total), so a green run answers
+  "how many assertions ran?" without `stdout` and a failing run's counts
+  match the `0 failures, 5 errors` line beside them. Both are `null` for
+  RSpec, which reports neither.
+
 ## 0.7.0
 
 - Add `rails_controller`: reports an `ActionController` controller's

data/README.md

@@ -57,8 +57,8 @@ MCP client
     v
 Coatepec parent (Rails-free)
     `-- private NDJSON --> test worker (Rails "test", booted lazily, kept warm)
-                              |-- Linux:  Process.fork  --> isolated RSpec child
-                              `-- macOS:  Process.spawn --> fresh RSpec process (default)
+                              |-- Linux:  Process.fork  --> isolated RSpec/Minitest child
+                              `-- macOS:  Process.spawn --> fresh RSpec/Minitest process (default)
                                           Process.fork, guarded --> opt-in, see Configuration
 ```
 
@@ -75,6 +75,11 @@ macos_fork_unsafe_gems: [some_gem]   # extends the built-in fork-unsafe denylist
 A missing file means every setting takes its default -- this file is never
 required.
 
+Tool responses are compact JSON -- no indentation, nothing downstream reads
+it. Set `COATEPEC_PRETTY=1` in the MCP server's `env` (the same place as
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY` in the JSON example below) to
+pretty-print them when you are reading the sidecar by hand.
+
 ### macOS fork (experimental, opt-in)
 
 On macOS, `rails_spec_run` normally spawns a fresh `bundle exec rspec`
@@ -125,34 +130,66 @@ a no-op.
 
 | Tool | Input | Notes |
 |---|---|---|
-| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120) | Isolated per run; output capped at 256 KiB per stream |
-| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state |
+| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120), `include_passing?`, `include_stdout?` (`failures` default, `always`, `never`) | RSpec (`spec/**/*_spec.rb`) or Minitest (`test/**/*_test.rb`), chosen from the paths; isolated per run; output capped at 256 KiB per stream; failure blocks in `stdout` that repeat an earlier block's error verbatim are replaced by a roll-up line naming the tests; returns `summary` counts (`example_count`, `failure_count`, `error_count`, `pending_count`, `assertion_count`, `duration`; the error and assertion counts come from Minitest and are `null` for RSpec) plus only the failed/pending `examples`, pass `include_passing: true` for the full roster (still capped at 500 examples); `stdout` is returned only for failing runs by default; `include_stdout: "always"` keeps it for green runs, `"never"` drops it always (the key stays, `null`); `stderr` is always returned; `child_pid`/`signaled`/`termsig`/`stopsig`/`coredump` appear only when the child did not exit normally (a timeout kill or a crash) |
+| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state, and the project root (`project_root`) |
 | `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot |
-| `rails_routes` | `query?`, `limit?` (1..200, default 50), `offset?` | Case-insensitive filter across name/verb/path/controller/action |
-| `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`) | ActiveRecord models only; columns, associations, validators, enums -- no row data |
+| `rails_routes` | `query?`, `limit?` (1..200, default 100), `offset?`, `engines?` (`exclude` default, `include`, `only`) | Returns `columns` (`name`, `verb`, `path`, `controller`, `action`, `engine`) and `rows` in that order; paths omit the `(.:format)` suffix Rails appends. Case-insensitive filter across name/verb/path/controller/action/engine. Application routes only by default; `engines: "include"` adds the routes of mounted engines (one level deep, paths prefixed with the mount point, `engine` naming the engine class; `null` for an application route), `"only"` returns just those. Every response carries `engines` (the filter applied) and `engines_excluded` (how many routes matching `query` the filter withheld), so nothing is hidden silently. The filter applies after `query` and before paging, so `matched`/`next_offset` describe the kept set. The engine's mount route counts as an application route. Routes Rails marks `internal` are omitted, like `bin/rails routes`. `next_offset` is the offset of the next page, or `null` on the last one |
+| `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`), `fields?` (any of `columns`, `associations`, `validators`, `enums`; omitted or `[]` means none) | Returns `name`, `table_name`, `primary_key`, `abstract_class` and `counts` (the size of each of the four lists, each capped at 200) by default and only the lists named in `fields` -- so a how-many question costs a few dozen bytes and `fields: ["columns"]` asks for the one list you need; ActiveRecord models only; columns, associations, validators, enums -- no row data; validators are de-duplicated by class, attributes and options (a concern and the model body declaring the same validation count once), so the count can be lower than `klass.validators.size`; an array-valued validator option longer than 20 entries (a country-code `inclusion` list, say) is cut to its first 20 with `<option>_count` and `<option>_truncated: true` beside it |
 | `rails_controller` | `name` (constant path, e.g. `WidgetsController` or `Admin::ReportsController`) | Actions, action callbacks, concerns, and the routes reaching each action -- no request dispatch |
-| `rails_spec_flaky_check` | `paths`, `example?`, `timeout_seconds?` (per round, 1..900), `runs?` (2..20, default 5) | Runs the selection `runs` times with a fresh random seed each round; reports examples whose status was inconsistent across runs |
+| `rails_spec_flaky_check` | `paths`, `example?`, `timeout_seconds?` (per round, 1..900), `runs?` (2..20, default 5) | Runs the selection `runs` times with a fresh random seed each round; reports tests whose status was inconsistent across runs; RSpec or Minitest, chosen from the paths |
 
 ### Example queries
 
 `rails_routes`:
 
-- "What are all the routes in this app?" -- `rails_routes()`
+- "What are all the routes in this app?" -- `rails_routes()`, the
+  application's own; add `engines: "include"` for the mounted engines' too.
 - "What's the URL for widgets?" -- `rails_routes(query: "widget")`. `query` is a
   case-insensitive substring match across name, verb, path, controller, *and*
   action -- not just the path -- so a resource name alone typically returns
   every route for that resource (index/create/new/...); narrow further with
-  something like `query: "new_widget"` to hit one route by name.
+  something like `query: "new_widget"` to hit one route by name. The call
+  already leaves out the admin engine's scaffolding, which is often two thirds
+  of every match; the response's `engines_excluded` says how many engine routes
+  it held back. Pass `engines: "include"` to see them too, or
+  `engines: "only"` for just the engine's.
 - "Which routes accept POST?" -- `rails_routes(query: "POST")`, the same
   substring match applied to the verb column.
+- "Which routes does the Avo engine add?" --
+  `rails_routes(query: "Avo::Engine", engines: "only")` -- the substring match
+  covers the `engine` column too, so an engine's class name returns exactly the
+  routes mounted from it. Application routes always sort before engine routes,
+  so an unfiltered listing (with `engines: "include"`) reads the way
+  `bin/rails routes` does.
+- An engine route's `name` is relative to its engine, not a top-level url
+  helper: the row `["audits", "GET", "/widget_admin/audits",
+  "widget_admin/audits", "index", "WidgetAdmin::Engine"]` is reached as
+  `widget_admin.audits_path` -- `<mount name>.<name>_path`, where the mount
+  name is the `name` of the mount route itself -- and `audits_path` alone
+  does not exist on the application.
+- An engine mounted at two paths is listed under both mount points, once per
+  prefixed path, whenever engine routes are in scope, since each of those
+  paths is a real, reachable URL.
+  `bin/rails routes` keys engines by endpoint and so lists such an engine
+  only once.
+- Paging: when `next_offset` is not `null`, call again with
+  `offset: next_offset` to get the next page.
 
 `rails_model`:
 
 - "What columns does Widget have, and which are nullable?" --
-  `rails_model(name: "Widget")` -- see `columns[].null`, `columns[].sql_type`,
-  `columns[].default`.
-- "What validations and associations does Widget enforce?" -- same call --
+  `rails_model(name: "Widget", fields: ["columns"])` -- see `columns[].null`,
+  `columns[].sql_type`, `columns[].default`.
+- "What validations and associations does Widget enforce?" --
+  `rails_model(name: "Widget", fields: ["validators", "associations"])` --
   see `validators` and `associations`.
+- "How many columns, associations, validators and enums does Event have?" --
+  `rails_model(name: "Event")` -- see `counts`; ask for the lists with
+  `fields` when you need them.
+- A long allow-list is summarised, not enumerated: `validates :country_code,
+  inclusion: { in: ISO_CODES }` with 249 codes comes back as `"in"` holding
+  the first 20, `"in_count": 249` and `"in_truncated": true`. A list of 20 or
+  fewer has no `_count`/`_truncated` siblings.
 - "What happens if I ask about a non-model class, like a controller?" --
   `rails_model(name: "ApplicationController")` raises `not_active_record_model`
   rather than introspecting it (a nonexistent constant raises `model_not_found`
@@ -162,9 +199,10 @@ a no-op.
 
 - "What actions does WidgetsController define, and what routes reach them?" --
   `rails_controller(name: "WidgetsController")` -- see `actions[].routes`,
-  each with `verb`, `path` (Rails' raw route spec, `(.:format)` suffix
-  included -- byte-identical to the same route's `path` from `rails_routes`),
-  and `route_name`.
+  each with `verb`, `path` (without the `(.:format)` suffix -- byte-identical
+  to the same route's `path` from `rails_routes`), `route_name`, and `engine`
+  (`null` for an application route, the engine's class name for a route that
+  reaches this controller through a mount).
 - "Does this controller have dead code, or a route that will 500?" -- same
   call -- see `unroutable_actions` (action methods no route reaches --
   probably dead code) and `routes_without_action` (action names the route
@@ -185,6 +223,12 @@ a no-op.
   `concerns`: app-defined modules only, whether included directly or
   inherited from a base class; framework modules (`ActionController::Base`
   and everything above it in the ancestor chain) are excluded.
+- Unlike `concerns`, `callbacks[]` is *not* filtered to app code: it is the
+  controller's full callback chain, so callbacks Rails itself installs show
+  up too -- `verify_authenticity_token` / `verify_same_origin_request` from
+  the default forgery protection, and a `"(block)"` entry for macros like
+  `allow_browser` that register a Proc. Read the list as "everything that
+  runs around an action", not "everything this app wrote".
 - `rails_controller` admits `ActionController::API` controllers as well as
   `ActionController::Base` ones. A malformed constant name raises
   `invalid_controller_name`; a name that doesn't resolve raises
@@ -192,18 +236,22 @@ a no-op.
   `ActionController` descendant (a plain class, a model) raises
   `not_action_controller`.
 
-`rails_controller` has two deliberate limitations, matching a boundary
-`rails_routes` already has:
+`rails_controller` has one deliberate limitation:
 
 - **Strong parameters are not reported.** `params.require(:widget).permit(:name,
   :size)` exists only as code inside a private method body, never as
   queryable class metadata -- the only way to recover a permit-list is to
   parse source, which this gem does not do (see `ROADMAP.md`'s "Considered
   and set aside" section for why source parsing is out of scope generally).
-- **Only the main app's route table is read.** A controller mounted inside an
-  engine will have its actions reported under `unroutable_actions` even where
-  the engine's own routes reach them -- `rails_routes` has the identical
-  boundary today.
+
+Routes drawn by an engine mounted in the application are cross-referenced
+like any other, with the mount point on the path and the engine's class name
+in `engine` -- so a controller that lives inside an engine reports its real
+routes rather than listing every action as unroutable. Their `route_name` is
+engine-local, reached as `<mount name>.<route_name>_path`, exactly as in
+`rails_routes`. Expansion goes one level deep: an engine mounted inside
+another engine stays an opaque mount route, the same boundary `bin/rails
+routes` (and therefore `rails_routes`) draws.
 
 `rails_spec_flaky_check`:
 
@@ -223,6 +271,8 @@ a no-op.
   `rails_spec_run` already has), and each round samples a different subset,
   since execution order varies by design -- for suites this large, narrow
   `paths`/`example` rather than passing a very broad directory selection.
+- `description` is only present when it differs from `id` (RSpec); Minitest
+  entries carry `id` only.
 - `statuses[]` only aligns positionally with `rounds[]` when no round
   crashed -- a round whose process itself failed contributes no entry to
   `statuses[]` (though it still appears in `rounds[]`), so treat positional
@@ -242,6 +292,30 @@ worker). For most apps this is invisible, but if you ever see behavior differ
 between Coatepec and your own `bundle exec rspec`, this is the first thing to
 suspect.
 
+Minitest through `rails_spec_run`:
+
+- "Run this Minitest file" -- `rails_spec_run(paths: ["test/models/widget_test.rb"])`;
+  the framework is decided by the path, and there is no separate
+  Minitest-named tool. `test/models/widget_test.rb:12` runs the one test
+  whose definition spans line 12, and a directory runs every `_test.rb`
+  under it.
+- `example:` is a substring match on the test's method name
+  (`example: "reaches the"` matches `test_reaches_the_database`), passed to
+  Minitest as an escaped regex.
+- Results use RSpec's vocabulary so the shape is identical: a Minitest skip
+  is `"pending"`, an error is `"failed"` and counts toward
+  `summary.failure_count` -- which is why that number can exceed the
+  `failures` Minitest prints in `stdout`; `summary.error_count` says how many
+  of them were errors, and `summary.assertion_count` is the assertion total
+  Minitest prints; `id` is `ClassName#test_method`.
+- One call may not mix `spec/` and `test/` paths (`mixed_test_frameworks`).
+- Rails' parallel testing is disabled in the child (`PARALLEL_WORKERS=1`), so
+  a large directory selection runs serially under the one timeout budget
+  rather than forking a worker tree.
+- `file:LINE` works even when the app was generated with `--skip-test` (no
+  `rails/test_unit/railtie`) or runs Rails 7.1 with Minitest 6, both of which
+  break Rails' own line filtering; Coatepec installs its own.
+
 ### Restarts
 
 If any tool call fails with `sidecar_restart_required`, the target app's
@@ -262,11 +336,12 @@ it always respawns, even if the current worker looks healthy.
 ## Security boundary
 
 No eval, console, SQL/record access, shell, Rake, or file-write tool. Spec
-selectors must resolve inside an allowed spec root (`spec/`, `packs/*/spec/`,
-`engines/*/spec/`, `gems/*/spec/`); absolute paths, `..`, symlink escapes,
-non-`_spec.rb` files, and more than 100 selectors are rejected. RSpec still
-executes application-controlled code; only run Coatepec against a trusted
-checkout.
+selectors must resolve inside an allowed spec or test root (`spec/`, `test/`,
+and the `packs/*/`, `engines/*/`, `gems/*/` variants of each); absolute
+paths, `..`, symlink escapes, files that are neither `_spec.rb` under a spec
+root nor `_test.rb` under a test root, and more than 100 selectors are
+rejected. RSpec and Minitest still execute application-controlled code; only
+run Coatepec against a trusted checkout.
 
 ### Compared to Rails Active MCP
 
@@ -279,8 +354,8 @@ sophisticated bypasses of a denylist like that are always possible in
 principle.
 
 Coatepec takes the opposite approach: there's no eval, console, or SQL
-tool to begin with. `rails_spec_run` only ever executes RSpec files that
-already exist under the app's own allowed spec roots, and `rails_routes`/
+tool to begin with. `rails_spec_run` only ever executes RSpec or Minitest
+files that already exist under the app's own allowed spec/test roots, and `rails_routes`/
 `rails_model`/`rails_controller` only ever call structured, read-only Rails
 APIs (`Rails.application.routes.routes`, `ActiveRecord` reflection,
 `ActionController` callback/action-method metadata) -- never `eval`,
@@ -291,9 +366,10 @@ structure without ever handing it a REPL.
 
 ## Compatibility
 
-Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`. CI tests three lanes: Rails 8.1 on
-Linux (primary), Rails 7.1 on Linux (compat), and Rails 8.1 on macOS (which
-is where the guarded-fork path above actually forks).
+Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`, Minitest 5.x and 6.x (the fixture
+apps pin 6.0.6; the 5.x name-filter flag is unit-tested). CI tests three
+lanes: Rails 8.1 on Linux (primary), Rails 7.1 on Linux (compat), and Rails
+8.1 on macOS (which is where the guarded-fork path above actually forks).
 
 ## Development
 

data/ROADMAP.md

@@ -4,56 +4,19 @@ Ideas and known future work for Coatepec, roughly in the order they came up.
 Nothing here is committed to a release; this is a place to write things down
 before they're designed, not a promise.
 
-## Minitest support
-
-Every current tool (`rails_spec_run`, `rails_spec_flaky_check`, and the
-paused `rails_spec_profile` below) is built around RSpec: `Coatepec::Spec::Runner`
-shells out to `bundle exec rspec`/forks an RSpec process, and
-`Coatepec::Spec::PathPolicy` validates selectors against RSpec's own
-`*_spec.rb` convention. None of that carries over to a Rails app using
-Minitest instead.
-
-The shape of the fix should mirror what already exists rather than
-invent something new: a parallel `Coatepec::Minitest::Runner` (or
-similarly named) implementing the same "validate selectors, build CLI
-args, run via the platform strategy, return a structured result" contract
-`Spec::Runner` already does, reusing `ForkStrategy`/`SpawnStrategy`/`GuardedForkStrategy`
-as-is where their logic is genuinely test-framework-agnostic (they mostly
-just fork/spawn a command and reap it — the RSpec-specific parts are
-`Runner#build_args` and the `--format json` output parsing in
-`Coatepec::Spec::Result`, both of which would need Minitest equivalents:
-Minitest's own JSON/machine-readable reporter, or `minitest-reporters`
-gem output, would need to be identified before designing that half).
-
-**Framework auto-detection via the Gemfile is straightforward and doesn't
-need new machinery** — `Coatepec::Worker::RailsRuntime#loaded_gem_names`
-already exists and is exactly the mechanism `GuardedForkStrategy` uses
-today to check for fork-unsafe gems, and `Coatepec::Spec::FactoryProfRunner`
-(see below) uses to check for `test-prof`. The same `loaded_gem_names.include?("rspec-rails")`
-vs. `.include?("minitest")` check (a Rails app's default `Gemfile` already
-declares one or the other, sometimes both) is enough to route
-`rails_spec_run` (or a to-be-decided `rails_test_run`, if the two
-frameworks' capabilities diverge enough to warrant separate tool names
-rather than one dispatching tool) to the right runner. `Coatepec::Spec::Runner#require_rspec!`
-already anticipates the gap in spirit: it raises `:unsupported_test_framework`
-today when `rspec-rails` isn't loadable, rather than assuming RSpec
-unconditionally.
-
-Open questions for whenever this gets designed properly:
-- One tool name that dispatches by detected framework, or separate
-  `rails_spec_run`/`rails_minitest_run`-style tools? (Affects whether an
-  agent needs to know which framework a given app uses before calling the
-  right tool, vs. the tool figuring it out.)
-- What Minitest gives you for structured per-example output
-  (pass/fail/pending, id, file/line) equivalent to RSpec's `--format json`
-  — needed before `rails_spec_flaky_check`'s per-example flaky-detection
-  logic (`Coatepec::Spec::FlakyChecker`, framework-agnostic in principle
-  since it only depends on `Runner#run`'s result shape) could target
-  Minitest too.
-- Whether Minitest's own `--seed` (it has one; Minitest randomizes test
-  order by default too) is enough of an equivalent to RSpec's `--seed`
-  for `rails_spec_flaky_check` to reuse the same "rerun N times with a
-  fresh random seed" mechanism unchanged.
+## Minitest support -- shipped in 0.8.0
+
+Shipped through the existing `rails_spec_run`/`rails_spec_flaky_check`
+tools. The open questions resolved as: one tool, dispatching by
+*selector shape* (`test/**/*_test.rb` vs `spec/**/*_spec.rb`) rather
+than by Gemfile, since that is per-request and unambiguous for apps
+with both; structured per-test output comes from an in-process
+`Minitest::AbstractReporter` writing RSpec's JSON shape, so
+`Spec::Result` and `FlakyChecker` were reused unchanged; and Minitest's
+`--seed` is a direct equivalent (16-bit, random order by default), so
+the flaky checker works as-is. See
+`docs/superpowers/specs/2026-09-05-minitest-support-design.md` (local-only)
+for the design and the line-filtering finding.
 
 ## Get stats on a spec/test run (TestProf / FactoryProf) — designed, implemented, paused
 
@@ -114,16 +77,16 @@ or folds into an existing one, and whether "security audits" specifically
 `bin/ci`) are worth exposing as a narrower, separate tool for apps that
 don't use Rails 8.1's `bin/ci` scaffold at all but do have those gems.
 
-## Controller introspection
+## Controller introspection -- shipped in 0.7.0
 
-A `rails_controller`-style tool mirroring the existing `rails_model`
-(`Coatepec::Introspection::Model`) and `rails_routes`
-(`Coatepec::Introspection::Routes`) tools' shape: given a controller
-constant, return its actions, `before_action`/`around_action`/`after_action`
-filters (and which actions they apply to), strong-parameter method
-definitions, and included concerns -- via real Rails introspection APIs
-(`ActionController::Base` callback chains, not source parsing), the same
-trust boundary `rails_model` already holds to.
+Shipped as `rails_controller` (`Coatepec::Introspection::Controller`) in
+0.7.0: actions, `before`/`after`/`around` callbacks with their `only`/`except`
+restrictions and `if`/`unless` conditions, included concerns, and a
+cross-reference of every action against `Rails.application.routes`
+(`unroutable_actions` / `routes_without_action`). Strong parameters were
+deliberately left out: a `permit` list exists only as code inside a method
+body, and recovering it would mean source parsing (see "Considered and set
+aside" below). See the README and CHANGELOG for the full contract.
 
 ## Background job introspection -- built, then parked (PR #14, closed unmerged)
 
@@ -171,9 +134,12 @@ Two constraints worth keeping if this is revisited:
 ## Cross-file consistency validation
 
 Distinct from anything coatepec does today: a tool that checks for drift
-*across* files rather than introspecting one thing at a time -- a route
-pointing at a controller action that doesn't exist, a `belongs_to`/`has_many`
-referencing a column or table that isn't in the schema, that kind of thing.
+*across* files rather than introspecting one thing at a time -- a
+`belongs_to`/`has_many` referencing a column or table that isn't in the
+schema, that kind of thing. (The route-to-missing-action case is already
+covered per controller by `rails_controller`'s `routes_without_action`,
+shipped in 0.7.0; an app-wide sweep of the whole route table would be the
+cross-file version of that same check.)
 Surfaced while researching prior art (a competing tool does this via
 source-code parsing); would need its own design for how to do it via
 structured Rails APIs instead, consistent with how every other coatepec

data/lib/coatepec/introspection/bounded_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Caps the array-valued entries of a sanitized validator options hash (see SafeOptions) for rails_model output:
+    # 249 country codes just say "allow-list", and the count plus flag beside a cut list keep it self-describing.
+    module BoundedOptions
+      module_function
+
+      def call(options, max)
+        options.each_with_object({}) do |(key, value), bounded|
+          bounded[key] = value
+          next unless value.is_a?(Array) && value.size > max
+
+          bounded[key] = value.first(max)
+          bounded["#{key}_count"] = value.size
+          bounded["#{key}_truncated"] = true
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/introspection/controller.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "route_entries"
+
 module Coatepec
   module Introspection
     # Returns bounded ActionController class metadata for a single controller,
     # for the rails_controller MCP tool. Pure reflection over an already-loaded,
     # already-gated class -- no request dispatch, no action execution, and no
     # evaluation of app-authored callback conditions.
-    # rubocop:disable Metrics/ClassLength -- Task 3 (route cross-referencing)
-    # adds genuinely cohesive functionality: routes_by_action, grouped_routes,
-    # route_data, and rails_routes exist solely to serve this class's single
-    # responsibility (reflect on one controller). Splitting them into a
-    # separate collaborator class would fragment that one responsibility
-    # across files for no readability gain, only to satisfy a line count.
+    # rubocop:disable Metrics/ClassLength -- the route cross-referencing methods serve this class's
+    # one responsibility (reflect on one controller); splitting them out would only satisfy a line count.
     class Controller
       NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
       MAX_ITEMS = 200
@@ -101,25 +99,20 @@ module Coatepec
         end
       end
 
-      # controller_path is the public, correctly-namespaced key Rails itself
-      # stores in a route's defaults (Admin::ReportsController =>
-      # "admin/reports"), so matching on it needs no name munging.
-      #
-      # Only Rails.application.routes is read, so a controller mounted inside
-      # an engine will report its actions as unroutable even though the
-      # engine's own route set reaches them. Introspection::Routes has exactly
-      # the same boundary today; it is documented in the README rather than
-      # silently absorbed.
-      # A route whose defaults[:action] is nil or empty (a mount or redirect)
-      # is skipped, not recorded under an empty-string action.
+      # Matches on controller_path, Rails' own key in route defaults ("admin/reports"), through
+      # RouteEntries so engine controllers resolve too. Routes with no action (mounts, redirects) are skipped.
       def routes_by_action(klass)
-        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |route| route_data(route) } }
+        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |entry| route_data(entry) } }
       end
 
       def grouped_routes(klass)
-        path = klass.controller_path
-        matching = self.class.rails_routes.select { |route| route.defaults[:controller].to_s == path }
-        matching.group_by { |route| route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+        entries = controller_entries(klass.controller_path)
+        entries.group_by { |entry| entry.route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+      end
+
+      def controller_entries(path)
+        RouteEntries.call(self.class.rails_routes)
+                    .select { |entry| entry.route.defaults[:controller].to_s == path }
       end
 
       # Differenced against the controller's full action_methods set, not the
@@ -128,19 +121,17 @@ module Coatepec
       # have every route whose action fell past the truncation point reported
       # here as a false positive, in the field the README calls the tool's
       # most actionable output. Bounded to MAX_ITEMS like every other
-      # collection in this payload; `grouped_routes` itself caps each route
+      # collection in this payload; `routes_by_action` itself caps each route
       # *list* but not its key count, so this is where that cap belongs.
       def routes_without_action(klass, routes)
         defined_actions = klass.action_methods.map(&:to_s)
         (routes.keys - defined_actions).sort.first(MAX_ITEMS)
       end
 
-      # path keeps Rails' raw spec, `(.:format)` suffix included, so a path
-      # string here is byte-identical to the same route as reported by
-      # rails_routes. Stripping it would make the two tools disagree about the
-      # same route.
-      def route_data(route)
-        { verb: route.verb.to_s, path: route.path.spec.to_s, route_name: route.name&.to_s }
+      # path and engine come off the entry, so they are byte-identical to rails_routes' values for the
+      # same route. An engine route's name is engine-local: reach it as `<mount name>.<route_name>_path`.
+      def route_data(entry)
+        { verb: entry.route.verb.to_s, path: entry.path, route_name: entry.route.name&.to_s, engine: entry.engine }
       end
 
       # Isolated as a class method purely so unit tests can stub it without