rigortype 0.3.8 → 0.4.0

data/plugins/rigor-actionpack/lib/rigor/plugin/actionpack.rb

@@ -6,6 +6,11 @@ require_relative "actionpack/analyzer"
 require_relative "actionpack/effects"
 require_relative "actionpack/controller_discoverer"
 require_relative "actionpack/controller_index"
+require_relative "actionpack/controller_scan"
+require_relative "actionpack/erb_compiler"
+require_relative "actionpack/render_locals"
+require_relative "actionpack/view_assigns"
+require_relative "actionpack/view_units"
 
 module Rigor
   module Plugin
@@ -55,6 +60,7 @@ module Rigor
     class Actionpack < Rigor::Plugin::Base
       manifest(
         id: "actionpack",
+        target_gems: ["actionpack"],
         # ADR-37: the four phases (helper / filter / render / strong-params) run per-call over the
         # engine-owned walk; the enclosing controller is read from the node-rule `NodeContext`
         # ancestors. Nested-module qualification is preserved — `module Admin; class
@@ -68,16 +74,78 @@ module Rigor
         # Bumped 2026-09-02 (#621) — a reopened controller's `def`s are UNIONed rather than clobbered by
         # the later file in the glob, so a cached 1.0.0 index can be missing the filter targets the merge
         # restores.
-        version: "1.1.0",
+        # Bumped 2026-09-17 (#393) — the plugin gained `template_globs:` and compiles `app/views/**/*.erb`
+        # into template units, so the answer for a project with views is a different answer entirely and
+        # a cached 1.2.0 run has no view rows in it.
+        # Bumped 2026-09-10 (#534 item 7) — the plugin gained a bundled `sig/` (ADR-25) naming the
+        # `ActionController` namespace and the errors controllers rescue, so the constants stop resolving
+        # to `untyped`. `ActionController::Parameters` and the `ActionDispatch` readers stay undeclared;
+        # `sig/action_controller.rbs` documents why that absence is load-bearing.
+        # Bumped 2026-09-17 (#1047) — the plugin now traces render-site `locals:` into a partial's unit and
+        # compiles LAYOUTS (a `yield` rewrite), so a cached 1.3.0 run is missing both the layout units and
+        # every seeded local.
+        # Bumped 2026-09-18 (#1065) — the claim grew the non-ERB handlers, which the plugin declines and
+        # the engine reads as "a template exists here and has no unit". The bump is belt-and-braces: what
+        # actually invalidates is the claim itself, through the glob row in `TemplateUnits#digest` and the
+        # `claimed_globs` equality the carry checks. A manifest version is in no cache key of its own.
+        version: "1.5.0",
         description: "Validates Action Pack route-helper calls and filter chains inside controllers, and types the request-context readers (`params` / `session` / `request` / `flash`) and their chains.",
         config_schema: {
           "controller_search_paths" => { kind: :array, default: ["app/controllers"] },
-          "view_search_paths" => { kind: :array, default: ["app/views"] }
+          "view_search_paths" => { kind: :array, default: ["app/views"] },
+          # #393 — whether the ordinary `call.*` type checks are reported INSIDE a compiled template. The
+          # `flow.*` family is no longer gated on this knob: #1047 removed the binding gap that made it
+          # unsound in a view, and it reports by default like every other family.
+          # Off by default: the synthesised `self` is an open receiver and the seeds are deliberately
+          # narrow, so the typing half of a view unit is not yet precise enough to be worth a diagnostic
+          # per template line, while the EFFECTS half needs no receiver precision at all and is what the
+          # view layer is analysed for first. A project that wants `@user.nmae` in `show.html.erb` can
+          # turn it on; see `docs/manual/plugins/rigor-actionpack.md`.
+          "view_type_checks" => { kind: :boolean, default: false }
         },
         consumes: [
           { plugin_id: "rails-routes", name: :helper_table, optional: true },
           { plugin_id: "activerecord", name: :model_index, optional: true }
         ],
+        # ADR-25 (#534 item 7) — the framework-namespace signatures. See `sig/action_controller.rbs` for
+        # the admission rule and, more importantly, for what it refuses to declare, and
+        # `sig/action_view.rbs` for the one class a template unit's `self` is typed as.
+        signature_paths: ["sig"],
+        # #393 — the ERB templates this plugin compiles into {Plugin::TemplateUnit}s. A manifest row is
+        # read without running plugin code, so it cannot consult `view_search_paths:`; a project that
+        # moves its views away from `app/views` gets no units, which is the quiet answer rather than a
+        # wrong one. Both `show.html.erb` and the bare `show.erb` shape are claimed.
+        # #1065 — the non-ERB handlers are claimed and DECLINED. Nothing here is compiled, and
+        # {#template_units_for_file} returns `[]` for every one of them; what the claim buys is the
+        # engine knowing a template exists at that logical name, which is what stops a `.js` render's
+        # format fallback from resolving past `_row.js.haml` onto `_row.html.erb`. Action View runs the
+        # Haml file. The list is the handlers a Rails app actually keeps under `app/views` — the common
+        # third-party template gems, plus Action View's own `builder` and `ruby`. It is NOT exhaustive:
+        # `raw` and `html` are Action View handlers too and are deliberately left out, because a claim on
+        # `*.html` would key a file whose name carries no format at all. A handler nobody claims is
+        # invisible, and its fallback behaves as it did before this claim existed.
+        template_globs: ["app/views/**/*.erb",
+                         "app/views/**/*.{haml,slim,jbuilder,builder,rabl,ruby}"],
+        # ADR-26 — every class the bundled signature names is declared so the CONSTANT resolves; none of
+        # them enumerates a method surface, so `ParameterMissing#param` and its siblings must stay
+        # lenient rather than becoming `call.undefined-method` on a rescue body.
+        open_receivers: [
+          "ActionController::ActionControllerError",
+          "ActionController::BadRequest",
+          "ActionController::RoutingError",
+          "ActionController::UrlGenerationError",
+          "ActionController::MethodNotAllowed",
+          "ActionController::NotImplemented",
+          "ActionController::UnknownFormat",
+          "ActionController::InvalidAuthenticityToken",
+          "ActionController::InvalidCrossOriginRequest",
+          "ActionController::MissingExactTemplate",
+          "ActionController::ParameterMissing",
+          "ActionController::UnpermittedParameters",
+          # #393 — the view context every template unit's `self` is typed as. Declared in
+          # `sig/action_view.rbs` so the name resolves, open so the helper surface stays lenient.
+          "ActionView::Base"
+        ],
         # ADR-103 WD10 / WD14 (#387) — see {Effects} for what each row is and why.
         effect_root: "rails",
         effect_labels: %w[
@@ -98,10 +166,202 @@ module Rigor
         ).discover
       end
 
+      # #393 / #1047 — the diagnostic family a compiled template does not report while `view_type_checks:`
+      # is off (its default). Measured rather than assumed, on the private corpus copies recorded in
+      # `docs/notes/20260917-erb-template-units.md` and `docs/notes/20260917-render-locals-and-layouts.md`.
+      #
+      # `call.` is the receiver-precision family. `self` is an open `ActionView::Base` and the seeds are
+      # deliberately narrow, so what this family would report about a view is mostly a statement about what
+      # the synthesis does not know yet.
+      #
+      # **`flow.` was here and is not any more (#1047).** It was suppressed for one measured reason: with
+      # no render-site `locals:`, redmine's standard optional-local preamble
+      # (`<% path = nil unless defined? path %>` in `app/views/common/_other.html.erb`) really did assign
+      # nil in the compiled Ruby, and the flow rules folded three live branches on a partial Rails renders
+      # correctly. {RenderLocals} binds those names from the three sites that render that partial, the
+      # preamble stops being a fresh assignment, and the corpus re-measured with `flow.` UNSUPPRESSED is
+      # byte-identical to the corpus with it suppressed — on redmine (506 templates, layouts included) and
+      # on mastodon (46). The suppression was a stand-in for a missing binding, so it goes when the binding
+      # arrives rather than staying as a habit.
+      SUPPRESSED_VIEW_RULES = ["call."].freeze
+
+      # #1047 — where the project's view helpers live, read only for the names they `def`: a template's
+      # `defined?(current_user)` tests a HELPER, not an optional local, and must not seed one
+      # ({ViewUnits.self_declared_locals}). Rails' own convention and not a config knob, for the reason
+      # `template_globs:` is not one either.
+      HELPER_SEARCH_PATHS = ["app/helpers"].freeze
+
       def init(_services)
         @controller_search_paths = Array(config.fetch("controller_search_paths")).map(&:to_s)
         @view_search_paths = Array(config.fetch("view_search_paths")).map(&:to_s)
+        @view_type_checks = config.fetch("view_type_checks") ? true : false
+      end
+
+      # #393 — one ERB template compiled into one {Plugin::TemplateUnit}. Called once per matched file, on
+      # the parent, before any analysis (ADR-16 Tier D as revived by #392).
+      #
+      # The three synthesised bindings and where each comes from:
+      #
+      # - `self_type:` — {ViewUnits::SELF_TYPE}, a declared-but-open `ActionView::Base`, so every helper
+      #   call resolves lenient rather than drawing a finding per line.
+      # - `locals:` — the names every RENDER SITE passes ({RenderLocals}, #1047), overlaid with the Rails
+      #   7.1 strict-locals comment where a template carries one. The seed is what makes Prism read `user`
+      #   as a local rather than as a method call, which is what a `defined? user` preamble needs.
+      # - `ivar_seeds:` — the assigns of the controller actions that render this template, through
+      #   {ViewAssigns}. A partial has none: its bindings belong to the render site.
+      #
+      # A compiler whose line numbering could not be measured declines the file rather than reporting at
+      # lines it cannot vouch for — {ErbCompiler::Unmappable} propagates, and the seam turns it into one
+      # `:plugin_loader` `runtime-error` row naming the template.
+      #
+      # ## Compiled Ruby that does not parse declines the file, silently
+      #
+      # A template is not Ruby, and the compiled form of one is not always Ruby either: a `case` split
+      # across tags with markup between the `case` and its first `when` is invalid anywhere. Handing such a
+      # body to the engine would put TWO parse diagnostics on a template Rails renders perfectly — a false
+      # positive per file, which is the one outcome this feature may not have (AGENTS.md). So the compiled
+      # Ruby is parsed and a body that does not parse declines the file through the seam's own `[]` door:
+      # no unit, no diagnostic, no effects.
+      #
+      # A LAYOUT used to be the bulk of that residue — `<%= yield %>` is legal ERB and illegal Ruby outside
+      # a method — and since #1047 it is not: {ErbCompiler::YIELD_METHOD} rewrites the keyword into a call
+      # on the view context, so all four of redmine's layouts and both of mastodon's compile. The residue
+      # is one `case` under stdlib ERB and none under Erubi.
+      #
+      # The cost is one Prism parse per template on the parent, and since #1047 both that parse and the
+      # compile are the ones {RenderLocals} already performed while building its index.
+      def template_units_for_file(path:, source:)
+        # #1065 — a claimed non-ERB handler is read for its NAME and nothing else: this plugin compiles
+        # ERB, and a `.haml` body handed to an ERB compiler would be garbage rather than a decline.
+        return [] unless path.end_with?(ERB_SUFFIX)
+
+        name = ViewUnits.logical_name(path, @view_search_paths)
+        # Scrubbed ONCE, here, and handed to both readers. Scrubbing inside the compiler alone left
+        # `ViewUnits.strict_locals` matching a Regexp against the raw bytes, and a single invalid byte
+        # anywhere in a template carrying a strict-locals comment raised out of the hook — which the seam
+        # correctly turns into an `error`-severity `:plugin_loader` row, so one mis-encoded view failed
+        # the whole run.
+        text = ErbCompiler.scrub(source)
+        revalidate_indexes
+        compiled, line_map, transform, parsed = render_locals.compiled_for(path, text) || compile_now(text)
+        return [] unless parsed
+
+        [
+          Rigor::Plugin::TemplateUnit.new(
+            logical_name: name, path: path, ruby_source: compiled, line_map: line_map,
+            self_type: ViewUnits::SELF_TYPE,
+            locals: template_locals(name, text),
+            ivar_seeds: view_assigns.seeds_for(name), transform_id: transform,
+            suppressed_rules: @view_type_checks ? [] : SUPPRESSED_VIEW_RULES
+          )
+        ]
+      end
+
+      # The compile the {RenderLocals} cache could not answer — an editor's in-flight bytes, or a template
+      # the index never globbed. Same four values the cache carries.
+      # The one handler this plugin compiles; every other claimed template is declined for its name.
+      ERB_SUFFIX = ".erb"
+
+      def compile_now(text)
+        compiled, line_map, transform = ErbCompiler.compile(text)
+        [compiled, line_map, transform, Prism.parse(compiled).errors.empty?]
+      end
+      private :compile_now
+
+      # A template's locals, from three sources that each say a name is bound, weakest first so the
+      # strongest wins a type: every name the template itself tests for with `defined?` or `local_assigns`
+      # (its author's own optional-local declaration, which needs no render site — #1047's review found
+      # the render-site index alone misses a `locals: opts` site, a helper-side `render` and a local no
+      # site passes at all), the render sites {RenderLocals} could read, and the strict-locals comment.
+      def template_locals(name, text)
+        ViewUnits.self_declared_locals(text, helpers: render_locals.helper_methods)
+                 .merge(render_locals.seeds_for(name))
+                 .merge(ViewUnits.strict_locals(text))
+      end
+      private :template_locals
+
+      # #1047 — the two parent-side indexes are memoised on this instance, and a long-lived
+      # `LanguageServer::ProjectContext` keeps the instance across publishes. A memo that is never
+      # revalidated keeps a render site's locals after the site changed on disk, which is a `flow.` row
+      # on a correct partial until the process restarts.
+      #
+      # So the indexes are revalidated once per COLLECTION PASS, against a fingerprint of every controller,
+      # helper and template they read ({RenderLocals::Builder.fingerprint}: one glob and one `stat` per
+      # file). The collector announces a pass through {#template_units_pass_started}; the check itself is
+      # deferred to the pass's first `#template_units_for_file`, so a warm pass that carries every unit and
+      # compiles nothing pays nothing. Inferring the pass from the order of paths was tried and is not
+      # enough: a warm pass offers only the editor's buffer, so switching buffers after a render site
+      # changed on disk was served from the stale index whichever way the two paths sorted.
+      #
+      # Revalidating at the FIRST call of the pass rather than when an edited template's own bytes arrive is
+      # load-bearing too: `_card.html.erb` globs before `show.html.erb`, so a reset triggered by `show` would
+      # come after `_card`'s unit had already been built from the stale index. The collector's whole-claim
+      # carry decision ({Analysis::TemplateUnitCollector}) is the other half: it is what re-offers `_card`.
+      def template_units_pass_started
+        @index_pass_pending = true
+      end
+
+      def revalidate_indexes
+        return unless @index_pass_pending
+
+        @index_pass_pending = false
+        drop_indexes unless indexes_fresh?
+      end
+      private :revalidate_indexes
+
+      def indexes_fresh?
+        return true if @render_locals.nil?
+
+        @render_locals.fingerprint == index_fingerprint
+      end
+      private :indexes_fresh?
+
+      def drop_indexes
+        @render_locals = nil
+        @view_assigns = nil
+      end
+      private :drop_indexes
+
+      def index_fingerprint
+        RenderLocals::Builder.fingerprint(
+          io_boundary: io_boundary, controller_search_paths: @controller_search_paths,
+          view_search_paths: @view_search_paths, helper_search_paths: HELPER_SEARCH_PATHS
+        )
+      rescue StandardError
+        nil
+      end
+      private :index_fingerprint
+
+      # The controller-assigns index, built once per run on the parent. Deliberately NOT a `producer` —
+      # a producer's value is cached against the run key, and this is consulted from the template-unit
+      # hook, which runs before the analysis a producer belongs to.
+      def view_assigns
+        @view_assigns ||= begin
+          ViewAssigns::Builder.new(io_boundary: io_boundary, search_paths: @controller_search_paths).build
+        rescue StandardError
+          ViewAssigns.empty
+        end
+      end
+      private :view_assigns
+
+      # #1047 — the render-site `locals:` index, and the compiled source every template was read through
+      # while it was built. Lazy and parent-only for the same reason {#view_assigns} is: it answers a
+      # question the analysis has not begun to ask yet. See {RenderLocals} for what a site contributes, and
+      # {#revalidate_indexes} for when a memoised index is dropped. A builder that raised is memoised as
+      # the empty index too — otherwise every hook call re-globbed and recompiled the project to fail
+      # again — and its nil fingerprint never equals a real one, so the next pass retries it.
+      def render_locals
+        @render_locals ||= begin
+          RenderLocals::Builder.new(
+            io_boundary: io_boundary, controller_search_paths: @controller_search_paths,
+            view_search_paths: @view_search_paths, helper_search_paths: HELPER_SEARCH_PATHS,
+            view_assigns: view_assigns
+          ).build
+        rescue StandardError
+          RenderLocals.empty
+        end
       end
+      private :render_locals
 
       # ADR-37 — the four Action Pack phases run per-call over the engine-owned walk. Each rule gates on
       # `controller_file?(path)` (the plugin only validates files under `controller_search_paths`,
@@ -144,7 +404,8 @@ module Rigor
         diagnostics_for(
           Analyzer.render_violations_for(
             call_node: node, ancestors: context.ancestors, path: path,
-            view_search_roots: @view_search_paths, controller_index: producer_value(:controller_index)
+            view_search_roots: @view_search_paths, io_boundary: io_boundary,
+            controller_index: producer_value(:controller_index)
           ),
           path: path, node: node
         )

data/plugins/rigor-actionpack/sig/action_controller.rbs

@@ -0,0 +1,71 @@
+# Action Pack's framework namespaces — issue #534 item 7.
+#
+# The 2026-09-01 corpus sweep counted `ActionController` 37 times on mastodon as an unresolved
+# constant. This file names the namespace and the errors controllers rescue, and nothing else.
+#
+# ## What must NOT be declared here, and why the list is so short
+#
+# `ActionController::Parameters` is absent on purpose, and it is the most important absence in this
+# plugin. `Rigor::Plugin::Actionpack::REQUEST_CONTEXT_READER_TYPES` types `params` as a *lenient*
+# nominal — a real class name Rigor ships no RBS for — precisely so that `params.require(...)`,
+# `params.to_unsafe_h` and every other member of a surface no signature can complete resolve
+# lenient-to-`Dynamic` instead of drawing `call.undefined-method`. Declaring the class here, even
+# empty, would make it RBS-known and undo that. The same argument covers `ActionDispatch::Request`,
+# `Request::Session`, `Flash::FlashHash`, `Flash::FlashNow` and `Cookies::CookieJar`.
+#
+# `ActionController::Base` and `ActionController::API` are absent for the stronger reason: every
+# controller in a Rails app inherits from one of them, so declaring either empty would close the
+# whole project's controller hierarchy and turn `render`, `before_action`, `head` and the rest into
+# `call.undefined-method` on working code.
+#
+# What is left is exactly the shape that is safe: bare namespace modules nobody dispatches on, and
+# exception classes whose inherited surface is a core Ruby one Rigor already carries. Each error
+# class is listed in the manifest's `open_receivers:` (ADR-26), so the framework-specific readers
+# this file does not enumerate (`ParameterMissing#param`, `UrlGenerationError#routes`, …) stay
+# lenient too.
+#
+# Superclasses transcribed from Rails v8.0.2 (`actionpack/lib/action_controller/metal/exceptions.rb`
+# and `strong_parameters.rb`); `ParameterMissing < KeyError` and `UnpermittedParameters < IndexError`
+# are the two that are NOT under `ActionControllerError`, and getting that wrong would be a wrong
+# `rescue` reachability answer, so both are stated from the source rather than from the pattern.
+
+module ActionController
+  class ActionControllerError < StandardError
+  end
+
+  class BadRequest < ActionControllerError
+  end
+
+  class RoutingError < ActionControllerError
+  end
+
+  class UrlGenerationError < ActionControllerError
+  end
+
+  class MethodNotAllowed < ActionControllerError
+  end
+
+  class NotImplemented < MethodNotAllowed
+  end
+
+  class UnknownFormat < ActionControllerError
+  end
+
+  class InvalidAuthenticityToken < ActionControllerError
+  end
+
+  class InvalidCrossOriginRequest < ActionControllerError
+  end
+
+  class MissingExactTemplate < UnknownFormat
+  end
+
+  # `::KeyError` is generic in core RBS (`KeyError[K, R]`, the receiver and key of the failed lookup),
+  # so the supertype has to be applied. `untyped` on both: Rails raises it from a Parameters lookup and
+  # this signature has no business claiming what `#receiver` / `#key` answer.
+  class ParameterMissing < ::KeyError[untyped, untyped]
+  end
+
+  class UnpermittedParameters < ::IndexError
+  end
+end

data/plugins/rigor-actionpack/sig/action_view.rbs

@@ -0,0 +1,43 @@
+# Action View's namespace — issue #393.
+#
+# `ActionView::Base` is the `self_type:` of every ERB template unit the plugin compiles. It is declared
+# here for one reason: so that the NAME resolves. `Analysis::TemplateUnits#seed` binds an unresolvable
+# `self_type:` to `Dynamic[top]`, which is silent but also tells the engine nothing, and a declared
+# receiver is what lets a later slice put a real helper surface behind it.
+#
+# ## Why it enumerates nothing
+#
+# The same argument `action_controller.rbs` makes about `ActionController::Parameters`, one step stronger.
+# A template's implicit-self calls are `link_to`, `form_with`, `t`, `l`, `cache`, `content_for`,
+# `image_tag`, `turbo_frame_tag`, every `*_path` / `*_url` route helper, every method in the project's own
+# `ApplicationHelper` and `<Controller>Helper`, every `helper_method` a controller exported, and whatever
+# the project's gems mixed in. No signature completes that surface, and a declared class DROPS every
+# member its signature omits — so enumerating the ten helpers the design note names would turn the other
+# thousand into `call.undefined-method` on working templates.
+#
+# So the class is named and left empty, and `open_receivers:` in the manifest (ADR-26) keeps its whole
+# method surface lenient. That is the "lenient / open receivers, never closed" posture stated as code.
+#
+# `ActionView::UnknownLocal` is deliberately ABSENT — see `ViewUnits::UNKNOWN_LOCAL`. It is the name a
+# strict-locals parameter is seeded with precisely because nothing resolves it, so the engine binds
+# `Dynamic[top]` while the local's NAME still reaches the parse.
+
+# ## The one declared member, and why it is not a helper
+#
+# `__rigor_yield` is issue #1047's reading of a LAYOUT's `yield`. `<%= yield %>` is legal ERB and illegal
+# Ruby outside a method body, so `ErbCompiler` rewrites the keyword into a call on this receiver before
+# either compiler runs — the template-unit seam does not wrap a unit's body in a synthesised method, so the
+# body has to parse as written. The name is not Rails', is not reachable from any template a user writes,
+# and exists only so the rewritten body resolves.
+#
+# It returns `String` and nothing narrower. Rails' `yield` hands back whatever the inner template's output
+# buffer holds and `yield :sidebar` hands back a `content_for` buffer (an empty `SafeBuffer`, never nil,
+# when nothing was provided); a lenient `String` is the
+# widest honest reading of that, and it is what keeps a layout from seeding a type the analyzer could not
+# justify. `*untyped` covers `yield`, `yield :sidebar` and `yield(:sidebar)` alike.
+
+module ActionView
+  class Base
+    def __rigor_yield: (*untyped) -> String
+  end
+end

data/plugins/rigor-active-model-serializers/lib/rigor/plugin/active_model_serializers/serializer_discoverer.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "rigor/source/node_children"
+
+require "prism"
+
+require_relative "serializer_index"
+
+module Rigor
+  module Plugin
+    class ActiveModelSerializers < Rigor::Plugin::Base
+      # Walks the configured serializer-search paths through the plugin's `IoBoundary`, parses each `.rb`
+      # file with Prism, records every `class X < Y` it finds with the facts the derivation needs, and
+      # keeps the classes whose ancestry closes back to a configured root:
+      #
+      #     class ApplicationSerializer < ActiveModel::Serializer   # root child
+      #     class REST::AccountSerializer < ApplicationSerializer   # reached through it
+      #
+      # The closure is what a direct-superclass match (the shape `rigor-pundit`'s policy discoverer uses)
+      # would miss, and a project base serializer is the common case rather than the exotic one. It is
+      # also the ONLY gate: a class the closure does not reach is not a serializer here, whatever it is
+      # called, because `object` is an ordinary name that any class may define.
+      #
+      # Every class in the scanned tree is recorded first and filtered afterwards, because the file that
+      # defines a base serializer may be parsed after the files that inherit from it.
+      class SerializerDiscoverer
+        # A `class << self` body is class-level for the same reason a `def self.x` body is, and it is a
+        # separate node type: without this arm a receiver-less `def object` inside one would register as
+        # an instance method, and an `object.<name>` there as a read of the resource.
+        SKIPPED_SCOPES = [Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+
+        # AMS's resource-backed declaration macros. Each names something the serializer renders by
+        # calling it on the resource, unless the serializer defines a method of that name itself.
+        DECLARATION_MACROS = %i[attributes attribute has_many has_one belongs_to].freeze
+
+        # Macros that DEFINE a method on the serializer rather than declaring one to read off the
+        # resource. `delegate :object, to: :wrapper` and `attr_reader :object` are both real ways to
+        # override AMS's reader, and neither writes a `def` for an ancestor walk to find; a name defined
+        # this way is also not a name the resource has to answer.
+        DEFINITION_MACROS = %i[attr_reader attr_accessor attr_writer delegate alias_method].freeze
+
+        # `object.tap`, `object.nil?`, `object.is_a?` and their siblings say nothing about which class the
+        # resource is, so they are not evidence.
+        #
+        # Listed rather than read from `Object.instance_methods`, which was the first shape and is
+        # process-dependent: `to_json`, `to_yaml` and `pretty_print` are on Object only because some
+        # library in the ANALYSER's process required them, so whether a serializer derived could change
+        # with Rigor's own load order. These are the public instance methods every Ruby object has from
+        # `Object` / `Kernel` alone.
+        UNIVERSAL_METHODS = %w[
+          ! != !~ <=> == === =~ __id__ __send__ class clone define_singleton_method display dup
+          enum_for eql? equal? extend freeze frozen? hash inspect instance_of? instance_variable_defined?
+          instance_variable_get instance_variable_set instance_variables is_a? itself kind_of? method
+          methods nil? object_id private_methods public_method public_methods public_send
+          remove_instance_variable respond_to? send singleton_class singleton_method singleton_methods
+          taint tainted? tap then to_enum to_s trust untaint untrust untrusted? yield_self
+        ].to_set.freeze
+
+        def initialize(io_boundary:, search_paths:, base_classes:)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+          @base_classes = base_classes.map { |name| name.to_s.delete_prefix("::") }
+        end
+
+        def discover
+          candidates = []
+          ruby_files_under(@search_paths).each do |path|
+            contents = read_safely(path)
+            next if contents.nil?
+
+            walk(Prism.parse(contents).value, []) do |entry_fields|
+              candidates << SerializerIndex::Entry.new(file_path: path, **entry_fields)
+            end
+          end
+          SerializerIndex.new(close_over_roots(candidates))
+        end
+
+        private
+
+        # Keeps only the classes whose declared-superclass chain reaches one of the roots. Iterating to a
+        # fixed point rather than recursing keeps a cyclic `class A < B; class B < A` source — which Ruby
+        # rejects but a static parse can still be handed — from recursing forever.
+        def close_over_roots(candidates)
+          by_name = candidates.to_h { |entry| [entry.class_name, entry] }
+          reached = @base_classes.to_set
+          loop do
+            grown = candidates.select do |entry|
+              !reached.include?(entry.class_name) && reached.include?(entry.superclass_name)
+            end
+            break if grown.empty?
+
+            grown.each { |entry| reached << entry.class_name }
+          end
+          reached.filter_map { |name| by_name[name] }
+        end
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          nil
+        end
+
+        def ruby_files_under(roots)
+          roots.flat_map do |root|
+            absolute = File.expand_path(root)
+            # ADR-45 WD1b (#613) — boundary-probed: a root that appears later invalidates the warm run.
+            next [] unless @io_boundary.directory?(absolute)
+
+            Dir.glob(File.join(absolute, "**", "*.rb"))
+          end
+        end
+
+        def walk(node, lexical_path, &)
+          return if node.nil?
+
+          case node
+          when Prism::ClassNode then visit_class(node, lexical_path, &)
+          when Prism::ModuleNode then visit_module(node, lexical_path, &)
+          else
+            node.rigor_each_child { |child| walk(child, lexical_path, &) }
+          end
+        end
+
+        def visit_class(node, lexical_path, &)
+          local_name = constant_path_name(node.constant_path)
+          return if local_name.nil?
+
+          superclass = node.superclass ? constant_path_name(node.superclass) : nil
+          unless superclass.nil?
+            yield({ class_name: qualify(lexical_path, local_name),
+                    superclass_name: superclass.delete_prefix("::"),
+                    **collect_facts(node.body) })
+          end
+
+          walk(node.body, lexical_path + [local_name], &) if node.body
+        end
+
+        def visit_module(node, lexical_path, &)
+          local_name = constant_path_name(node.constant_path)
+          return if local_name.nil?
+
+          walk(node.body, lexical_path + [local_name], &) if node.body
+        end
+
+        # The three name sets, gathered in ONE pass over the class body. A nested class or module is not
+        # descended into — its `def`s and its `object` reads belong to it, not to this class.
+        def collect_facts(body)
+          facts = { declared_names: Set.new, object_reads: Set.new, own_method_names: Set.new }
+          collect_from(body, facts)
+          facts.transform_values { |set| set.to_a.sort.freeze }
+        end
+
+        def collect_from(node, facts)
+          return if node.nil? || SKIPPED_SCOPES.any? { |kind| node.is_a?(kind) }
+
+          case node
+          when Prism::DefNode
+            # A `def self.x` body is class-level: its `object` would be a NoMethodError at run time, so
+            # neither its name nor its reads are evidence about the resource.
+            return unless node.receiver.nil?
+
+            facts[:own_method_names] << node.name.to_s
+          when Prism::CallNode then record_call(node, facts)
+          end
+          node.rigor_each_child { |child| collect_from(child, facts) }
+        end
+
+        def record_call(node, facts)
+          if node.receiver.nil? && DECLARATION_MACROS.include?(node.name)
+            symbol_arguments(node).each { |name| facts[:declared_names] << name }
+          elsif node.receiver.nil? && DEFINITION_MACROS.include?(node.name)
+            symbol_arguments(node).each { |name| facts[:own_method_names] << name }
+          elsif object_reader?(node.receiver) && !UNIVERSAL_METHODS.include?(node.name.to_s)
+            facts[:object_reads] << node.name.to_s
+          end
+        end
+
+        def object_reader?(receiver)
+          receiver.is_a?(Prism::CallNode) && receiver.name == :object && receiver.receiver.nil? &&
+            receiver.arguments.nil?
+        end
+
+        def symbol_arguments(node)
+          (node.arguments&.arguments || []).filter_map do |argument|
+            argument.unescaped if argument.is_a?(Prism::SymbolNode)
+          end
+        end
+
+        # `class REST::AccountSerializer` inside no module is already fully qualified; a class written as
+        # `class AccountSerializer` inside `module REST` is not. A name the source rooted explicitly
+        # (`class ::AccountSerializer`) keeps neither the root marker nor the lexical prefix.
+        def qualify(lexical_path, local_name)
+          return local_name.delete_prefix("::") if local_name.start_with?("::")
+
+          (lexical_path + [local_name]).join("::")
+        end
+
+        def constant_path_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_parts(node)
+          end
+        end
+
+        def constant_path_parts(node)
+          parts = []
+          current = node
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+          case current
+          when nil then "::#{parts.join('::')}"
+          when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+          end
+        end
+      end
+    end
+  end
+end