rigortype 0.2.7 → 0.2.9

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/devise_routes.rb

@@ -3,53 +3,35 @@
 module Rigor
   module Plugin
     class RailsRoutes < Rigor::Plugin::Base
-      # Generates the catalogue of route helpers a `devise_for
-      # :resources` call adds to a Rails app's routing table.
-      # The set is fixed and well-documented (the
-      # [Devise wiki](https://github.com/heartcombo/devise/wiki/How-To:-Add-routes-helpers)
-      # enumerates every generated helper); the generator
-      # mirrors it.
+      # Generates the catalogue of route helpers a `devise_for :resources` call adds to a Rails app's
+      # routing table. The set is fixed and well-documented (the
+      # [Devise wiki](https://github.com/heartcombo/devise/wiki/How-To:-Add-routes-helpers) enumerates
+      # every generated helper); the generator mirrors it.
       #
-      # Used by `RoutesParser` when it sees a top-level
-      # `devise_for :name` (or `devise_for :name, skip:
-      # [...]`) call. Each generated helper is materialised as
-      # a `HelperTable::Entry` so the analyzer's
-      # `unknown-helper` rule recognises them and the arity
-      # check accepts the canonical signatures (Devise helpers
-      # take zero positional args plus an optional trailing
-      # options hash, which `HelperTable#accepts_arity?`
-      # already handles via the `arity + 1` rule).
+      # Used by `RoutesParser` when it sees a top-level `devise_for :name` (or `devise_for :name, skip:
+      # [...]`) call. Each generated helper is materialised as a `HelperTable::Entry` so the analyzer's
+      # `unknown-helper` rule recognises them and the arity check accepts the canonical signatures (Devise
+      # helpers take zero positional args plus an optional trailing options hash, which
+      # `HelperTable#accepts_arity?` already handles via the `arity + 1` rule).
       #
       # Scope:
       #
-      # - Recognises the standard six controllers
-      #   (`:sessions`, `:passwords`, `:confirmations`,
-      #   `:unlocks`, `:registrations`, `:omniauth_callbacks`).
-      # - Honours `skip: [...]` to suppress controllers the
-      #   project disables.
-      # - Honours `path: "..."` to remap the URL path (does
-      #   NOT remap the helper-name prefix — Devise uses the
-      #   resource name for the helper, not the path).
-      # - Does NOT yet honour `as: "..."` overrides, `class_name:`,
-      #   `controllers: { ... }` (these are rare; expand on
-      #   demand).
-      # - `omniauth_callbacks` helpers are dynamic — the
-      #   provider name is supplied at call time
-      #   (`user_facebook_omniauth_authorize_path`) and Devise
-      #   declares them from the configured providers, which
-      #   live in an initializer this static parser does not
-      #   read. The suffix patterns are registered in
-      #   `OMNIAUTH_SUFFIXES` and consulted by
-      #   `HelperTable#omniauth_match?`.
+      # - Recognises the standard six controllers (`:sessions`, `:passwords`, `:confirmations`, `:unlocks`,
+      #   `:registrations`, `:omniauth_callbacks`).
+      # - Honours `skip: [...]` to suppress controllers the project disables.
+      # - Honours `path: "..."` to remap the URL path (does NOT remap the helper-name prefix — Devise uses
+      #   the resource name for the helper, not the path).
+      # - Does NOT yet honour `as: "..."` overrides, `class_name:`, `controllers: { ... }` (these are rare;
+      #   expand on demand).
+      # - `omniauth_callbacks` helpers are dynamic — the provider name is supplied at call time
+      #   (`user_facebook_omniauth_authorize_path`) and Devise declares them from the configured providers,
+      #   which live in an initializer this static parser does not read. The suffix patterns are registered
+      #   in `OMNIAUTH_SUFFIXES` and consulted by `HelperTable#omniauth_match?`.
       module DeviseRoutes
-        # The standard Devise controllers and the helper
-        # actions each generates. Keys are the controller
-        # name; values are arrays of `[helper_prefix,
-        # http_method, action]` triples — `helper_prefix` is
-        # the part BEFORE the resource-name segment (Rails
-        # produces `<prefix>_<resource>_<suffix>_path`; for
-        # the bare `<resource>_session_path` shape the prefix
-        # is empty).
+        # The standard Devise controllers and the helper actions each generates. Keys are the controller
+        # name; values are arrays of `[helper_prefix, http_method, action]` triples — `helper_prefix` is
+        # the part BEFORE the resource-name segment (Rails produces `<prefix>_<resource>_<suffix>_path`;
+        # for the bare `<resource>_session_path` shape the prefix is empty).
         CONTROLLER_HELPERS = {
           sessions: [
             ["new", "session", :get, :new],
@@ -77,13 +59,10 @@ module Rigor
           ]
         }.freeze
 
-        # Dynamic-provider helper patterns. `_omniauth_authorize_path`
-        # and `_omniauth_callback_path` are generated per
-        # configured provider (Facebook, GitHub, …) by an
-        # initializer this parser does not read. We treat any
-        # `<resource>_<provider>_omniauth_(authorize|callback)_(path|url)`
-        # call as recognised when the resource is one the
-        # project declared via `devise_for`.
+        # Dynamic-provider helper patterns. `_omniauth_authorize_path` and `_omniauth_callback_path` are
+        # generated per configured provider (Facebook, GitHub, …) by an initializer this parser does not
+        # read. We treat any `<resource>_<provider>_omniauth_(authorize|callback)_(path|url)` call as
+        # recognised when the resource is one the project declared via `devise_for`.
         OMNIAUTH_SUFFIXES = %w[
           _omniauth_authorize_path _omniauth_authorize_url
           _omniauth_callback_path _omniauth_callback_url
@@ -91,16 +70,12 @@ module Rigor
 
         module_function
 
-        # @param resource [String, Symbol] the `devise_for`
-        #   argument — typically `:users`. Used as both the
-        #   helper-name segment (`new_user_session_path`) and
-        #   to derive the resource path.
-        # @param skip [Array<Symbol>] controllers the project
-        #   disables via `devise_for :users, skip: [:registrations]`.
-        # @return [Array<HelperTable::Entry>] one entry per
-        #   generated `_path` helper. The caller is expected to
-        #   pair `_url` variants the same way `RoutesParser` does
-        #   for other entries.
+        # @param resource [String, Symbol] the `devise_for` argument — typically `:users`. Used as both the
+        #   helper-name segment (`new_user_session_path`) and to derive the resource path.
+        # @param skip [Array<Symbol>] controllers the project disables via `devise_for :users, skip:
+        #   [:registrations]`.
+        # @return [Array<HelperTable::Entry>] one entry per generated `_path` helper. The caller is
+        #   expected to pair `_url` variants the same way `RoutesParser` does for other entries.
         def generate(resource:, skip: [])
           resource_segment = singularize(resource.to_s)
           skip_set = skip.to_set(&:to_sym)
@@ -126,21 +101,15 @@ module Rigor
             end
           end
 
-          # Devise also ships *scoped* helpers
-          # (`Devise::Controllers::UrlHelpers`) that DROP the
-          # resource segment and take the scope as a positional
-          # argument: `new_password_path(resource_name)` is the
+          # Devise also ships *scoped* helpers (`Devise::Controllers::UrlHelpers`) that DROP the resource
+          # segment and take the scope as a positional argument: `new_password_path(resource_name)` is the
           # bare form of `new_user_password_path`. Used inside
-          # `Auth::PasswordsController < Devise::PasswordsController`
-          # (Mastodon's idiom). Arity 1 (the scope), and a
-          # trailing options-hash bumps it via the existing
-          # `arity + 1` rule.
+          # `Auth::PasswordsController < Devise::PasswordsController` (Mastodon's idiom). Arity 1 (the
+          # scope), and a trailing options-hash bumps it via the existing `arity + 1` rule.
           entries.concat(scoped_helpers(skip_set))
 
-          # `omniauth_authorize_path(scope, provider)` and
-          # `omniauth_callback_path(scope, provider)` are
-          # `Devise::Controllers::UrlHelpers` scoped helpers
-          # that delegate to the OmniAuth gem. Arity 2.
+          # `omniauth_authorize_path(scope, provider)` and `omniauth_callback_path(scope, provider)` are
+          # `Devise::Controllers::UrlHelpers` scoped helpers that delegate to the OmniAuth gem. Arity 2.
           unless skip_set.include?(:omniauth_callbacks)
             %w[omniauth_authorize_path omniauth_callback_path].each do |name|
               entries << HelperTable::Entry.new(
@@ -156,11 +125,9 @@ module Rigor
           entries
         end
 
-        # Scoped helpers Devise exposes inside its controllers.
-        # The arity-1 family — caller supplies the resource
-        # scope (`:user` etc.) as the first positional arg.
-        # Names mirror the qualified `<scope>_<name>_path`
-        # entries above, minus the scope segment.
+        # Scoped helpers Devise exposes inside its controllers. The arity-1 family — caller supplies the
+        # resource scope (`:user` etc.) as the first positional arg. Names mirror the qualified
+        # `<scope>_<name>_path` entries above, minus the scope segment.
         SCOPED_HELPERS = {
           sessions: %w[new_session_path session_path destroy_session_path],
           passwords: %w[new_password_path edit_password_path password_path],
@@ -186,28 +153,22 @@ module Rigor
           end
         end
 
-        # Returns the set of OmniAuth pattern suffixes the
-        # analyzer accepts for a given resource. The analyzer
-        # consults this set (via `HelperTable#omniauth_match?`)
-        # when a `*_path` / `*_url` call's name does not match
-        # any registered entry and its prefix matches a Devise
-        # resource.
+        # Returns the set of OmniAuth pattern suffixes the analyzer accepts for a given resource. The
+        # analyzer consults this set (via `HelperTable#omniauth_match?`) when a `*_path` / `*_url` call's
+        # name does not match any registered entry and its prefix matches a Devise resource.
         def omniauth_suffixes
           OMNIAUTH_SUFFIXES
         end
 
-        # ADR-39 — delegates to the shared inflector (real
-        # `ActiveSupport::Inflector` when available), replacing the tiny
-        # AS-replica this module used to duplicate from `RoutesParser`.
+        # ADR-39 — delegates to the shared inflector (real `ActiveSupport::Inflector` when available),
+        # replacing the tiny AS-replica this module used to duplicate from `RoutesParser`.
         def singularize(word)
           Rigor::Plugin::Inflector.singularize(word)
         end
 
-        # Approximate path generation. We don't honour the
-        # `path:` Devise option here because the helper NAME
-        # is what the analyzer cares about; the `path` field is
-        # informational and surfaces only in the `:helper` info
-        # diagnostic.
+        # Approximate path generation. We don't honour the `path:` Devise option here because the helper
+        # NAME is what the analyzer cares about; the `path` field is informational and surfaces only in
+        # the `:helper` info diagnostic.
         def devise_path_for(resource_segment, controller, action)
           plural = "#{resource_segment}s"
           base = "/#{plural}"

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/doorkeeper_routes.rb

@@ -3,39 +3,27 @@
 module Rigor
   module Plugin
     class RailsRoutes < Rigor::Plugin::Base
-      # Generates the catalogue of OAuth route helpers a
-      # `use_doorkeeper do ... end` block adds to a Rails app's
-      # routing table. The set is the Doorkeeper gem's
-      # documented default — see Doorkeeper's
-      # [Routing](https://github.com/doorkeeper-gem/doorkeeper/wiki/Customizing-routes)
-      # documentation; this module mirrors the canonical
-      # helper names.
+      # Generates the catalogue of OAuth route helpers a `use_doorkeeper do ... end` block adds to a Rails
+      # app's routing table. The set is the Doorkeeper gem's documented default — see Doorkeeper's
+      # [Routing](https://github.com/doorkeeper-gem/doorkeeper/wiki/Customizing-routes) documentation; this
+      # module mirrors the canonical helper names.
       #
-      # Used by `RoutesParser` when it sees a `use_doorkeeper`
-      # call. Each generated helper is materialised as a
-      # `HelperTable::Entry` so the analyzer's
-      # `unknown-helper` rule recognises them. Arity for the
-      # `oauth_application_path(:id)` / `oauth_authorized_application_path(:id)`
-      # forms is 1 (the `:id`); all other Doorkeeper helpers
-      # are arity 0.
+      # Used by `RoutesParser` when it sees a `use_doorkeeper` call. Each generated helper is materialised
+      # as a `HelperTable::Entry` so the analyzer's `unknown-helper` rule recognises them. Arity for the
+      # `oauth_application_path(:id)` / `oauth_authorized_application_path(:id)` forms is 1 (the `:id`);
+      # all other Doorkeeper helpers are arity 0.
       #
       # Scope:
       #
-      # - Recognises the standard helper set: authorization,
-      #   token, revoke, introspect, token_info, userinfo,
-      #   applications (resources), authorized_applications.
-      # - Honours `skip_controllers <names>` inside the block
-      #   to omit the named controller's helpers.
-      # - Does NOT yet honour `controllers ...:` remappings —
-      #   those change WHICH class serves the route but not
-      #   the helper NAMES, so omitting them is sound.
-      # - Does NOT yet honour custom `as:` / `at:` on
-      #   `use_doorkeeper` itself.
+      # - Recognises the standard helper set: authorization, token, revoke, introspect, token_info,
+      #   userinfo, applications (resources), authorized_applications.
+      # - Honours `skip_controllers <names>` inside the block to omit the named controller's helpers.
+      # - Does NOT yet honour `controllers ...:` remappings — those change WHICH class serves the route but
+      #   not the helper NAMES, so omitting them is sound.
+      # - Does NOT yet honour custom `as:` / `at:` on `use_doorkeeper` itself.
       module DoorkeeperRoutes
-        # Per-controller helper catalogue. Keys are the
-        # `skip_controllers :<key>` names; values are the
-        # entries (name + arity + path + http_method).
-        # Both `_path` and `_url` variants are paired by
+        # Per-controller helper catalogue. Keys are the `skip_controllers :<key>` names; values are the
+        # entries (name + arity + path + http_method). Both `_path` and `_url` variants are paired by
         # `RoutesParser` after registration.
         CONTROLLER_HELPERS = {
           authorizations: [
@@ -78,8 +66,7 @@ module Rigor
 
         module_function
 
-        # @param skip [Array<Symbol>] controller names the
-        #   project omits via `skip_controllers :name, ...`.
+        # @param skip [Array<Symbol>] controller names the project omits via `skip_controllers :name, ...`.
         # @return [Array<HelperTable::Entry>] flattened entries.
         def generate(skip: [])
           skip_set = skip.to_set(&:to_sym)

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/grape_api_discoverer.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class RailsRoutes < Rigor::Plugin::Base
+      # Recognises the helper *namespaces* the `grape-path-helpers` gem generates, so a call to one of them
+      # does not false-fire `unknown-helper`.
+      #
+      # The gem names each helper after its route's path segments, joined with `_`
+      # (`DecoratedRoute#path_helper_name`): `/api/:version/groups/:id/badges` under `version 'v4'` becomes
+      # `api_v4_groups_badges_path`. It walks `Grape::API::Instance.routes` — the *runtime* route table — and
+      # real grape sources build that table with metaprogramming (GitLab's `%w[group project].each { |t|
+      # resource t.pluralize … }`). A static parser cannot enumerate those names, and deriving only the
+      # easy ones would be worse than deriving none: every route it missed would keep firing on working
+      # code.
+      #
+      # What IS static is the leading segments. `prefix :api` contributes the first; `version 'v4'`
+      # contributes the second when the strategy is `:path` (Grape's default — `using: :header` / `:param`
+      # keeps the version out of the URL, and so out of the helper name). Both are literal arguments in the
+      # body of a class whose superclass chain reaches `Grape::API`. Everything after them is opaque.
+      #
+      # So the namespace `api_v4_…_path` is treated as open — a name the project's routes may define but
+      # Rigor cannot enumerate, so proving it undefined is unsound (the ADR-26 `open_receivers` reasoning,
+      # already applied in this plugin to Devise's runtime-provider OmniAuth family). Teeth survive where the
+      # gem's own contract keeps them sound: it defines no `_url` helper
+      # (`NamedRouteMatcher#method_missing` returns `super` unless the name ends `_path`), so
+      # `api_v4_anything_url` still fires, as does any name outside a declared prefix.
+      #
+      # Design note: `docs/notes/20260710-grape-path-helper-namespace.md`.
+      module GrapeApiDiscoverer
+        # A class is a grape API when its superclass chain reaches one of these. `Grape::API::Instance` is
+        # what a mounted `Grape::API` subclass actually becomes, and real code inherits from it directly
+        # (GitLab's `API::Base < Grape::API::Instance`).
+        GRAPE_BASE_NAMES = ["Grape::API", "Grape::API::Instance"].freeze
+
+        # `version 'v4', using: :path` puts the version in the URL. `:header` / `:param` do not, so those
+        # versions contribute no helper-name segment. Grape's default strategy is `:path`.
+        PATH_VERSION_STRATEGY = :path
+
+        module_function
+
+        # @param contents_per_path [Hash{String => String}] file path → source text, read by the caller
+        #   (through the trusted `IoBoundary`, so cache invalidation works).
+        # @return [Array<String>] the recognised helper-name prefixes (`["api_v3", "api_v4"]`). Empty when
+        #   the project declares no grape API — nothing changes for such a project.
+        def discover(contents_per_path)
+          declarations = {}
+          superclasses = {}
+          contents_per_path.each_value do |contents|
+            collect_from_contents(contents, declarations, superclasses)
+          rescue StandardError
+            # Best-effort: a parse failure in one grape file must not abort discovery for the rest. The core
+            # pipeline surfaces the parse error separately.
+            next
+          end
+          prefixes_for(declarations, superclasses)
+        end
+
+        # Composes `prefix` × `version` into helper-name prefixes, for grape classes only. A class with a
+        # prefix and no path-strategy version contributes the bare prefix; one with versions and no prefix
+        # contributes each version alone.
+        def prefixes_for(declarations, superclasses)
+          declarations.filter_map do |class_name, declaration|
+            next unless grape_api?(class_name, superclasses)
+
+            segments = declaration[:prefix]
+            versions = declaration[:versions]
+            next segments.join("_") if versions.empty? && !segments.empty?
+
+            versions.map { |version| (segments + [version]).join("_") }
+          end.flatten.reject(&:empty?).uniq
+        end
+
+        # Follows the recorded superclass chain (cycle-guarded) looking for a grape base. The chain lives
+        # entirely inside the scanned files, so an unresolvable parent simply ends the walk.
+        def grape_api?(class_name, superclasses)
+          seen = {}
+          current = class_name
+          while current && !seen[current]
+            seen[current] = true
+            parent = superclasses[current]
+            return true if parent && GRAPE_BASE_NAMES.include?(parent)
+
+            current = parent
+          end
+          false
+        end
+
+        def collect_from_contents(contents, declarations, superclasses)
+          root = Prism.parse(contents).value
+          walk(root, [], declarations, superclasses)
+        end
+
+        def walk(node, prefix_path, declarations, superclasses)
+          return unless node.is_a?(Prism::Node)
+
+          if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+            name = constant_name(node.constant_path)
+            if name
+              qualified = (prefix_path + [name]).join("::")
+              record_class(node, qualified, declarations, superclasses) if node.is_a?(Prism::ClassNode)
+              walk(node.body, prefix_path + [name], declarations, superclasses) if node.body
+              return
+            end
+          end
+
+          node.compact_child_nodes.each { |child| walk(child, prefix_path, declarations, superclasses) }
+        end
+
+        def record_class(node, qualified, declarations, superclasses)
+          parent = constant_name(node.superclass)
+          superclasses[qualified] = parent if parent
+          declaration = { prefix: [], versions: [] }
+          statements_of(node.body).each { |statement| absorb_declaration(statement, declaration) }
+          declarations[qualified] = declaration unless declaration[:prefix].empty? && declaration[:versions].empty?
+        end
+
+        # `prefix :api` / `prefix 'api/v2'` (a multi-segment prefix splits on `/`), and `version 'v4'` /
+        # `version 'v4', using: :path` — both in block and non-block form.
+        def absorb_declaration(node, declaration)
+          return unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+          case node.name
+          when :prefix
+            value = literal_value(first_argument(node))
+            declaration[:prefix] = value.split("/").reject(&:empty?) if value
+          when :version
+            value = literal_value(first_argument(node))
+            declaration[:versions] << value if value && path_strategy?(node)
+          end
+        end
+
+        # True unless an explicit `using:` names a non-path strategy. Grape defaults to `:path`.
+        def path_strategy?(node)
+          arguments = node.arguments&.arguments || []
+          keywords = arguments.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+          return true if keywords.nil?
+
+          using = keywords.elements.find do |element|
+            element.is_a?(Prism::AssocNode) && literal_value(element.key) == "using"
+          end
+          return true if using.nil?
+
+          literal_value(using.value) == PATH_VERSION_STRATEGY.to_s
+        end
+
+        def first_argument(node)
+          node.arguments&.arguments&.first
+        end
+
+        # Symbol and String literals only. A computed prefix / version is not a declaration we can ground a
+        # namespace in, so it contributes nothing.
+        def literal_value(node)
+          case node
+          when Prism::SymbolNode, Prism::StringNode then node.unescaped
+          end
+        end
+
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parent = node.parent
+          own = node.name&.to_s
+          return nil unless own
+          return own if parent.nil? # `::Foo` — a cbase root
+
+          parent_name = constant_name(parent)
+          parent_name ? "#{parent_name}::#{own}" : own
+        end
+
+        def statements_of(body)
+          case body
+          when Prism::StatementsNode then body.body
+          when Prism::BeginNode then statements_of(body.statements)
+          when nil then []
+          else [body]
+          end
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/helper_discoverer.rb

@@ -5,76 +5,54 @@ require "prism"
 module Rigor
   module Plugin
     class RailsRoutes < Rigor::Plugin::Base
-      # Walks `app/helpers/**/*.rb` (or any configured set of
-      # helper directories) and extracts every public
-      # module-level method name so the analyzer's
-      # `unknown-helper` rule does not false-fire on calls to
-      # project-defined `*_path` / `*_url` helpers (the
-      # canonical Rails pattern: a `UrlHelper` module exposing
-      # `full_asset_url`, `host_to_url`, `frontend_asset_url`,
-      # and so on).
+      # Walks `app/helpers/**/*.rb` (or any configured set of helper directories) and extracts every public
+      # module-level method name so the analyzer's `unknown-helper` rule does not false-fire on calls to
+      # project-defined `*_path` / `*_url` helpers (the canonical Rails pattern: a `UrlHelper` module
+      # exposing `full_asset_url`, `host_to_url`, `frontend_asset_url`, and so on).
       #
       # The discoverer is deliberately conservative:
       #
-      # - Walks `def name(...)` declarations at the module /
-      #   class top level. Nested `def` inside a method body or
-      #   a `define_method` macro is NOT extracted (the same
-      #   reason `rigor-actionpack` is not the canonical
-      #   custom-helper source — metaprogrammed helpers are out
-      #   of scope for a static scan).
-      # - **Visibility-agnostic.** A `private` / `protected`
-      #   `def some_url` IS registered. The `unknown-helper`
-      #   rule is a project-wide name-presence check, not a
-      #   visibility check — if the user wrote a `_path` /
-      #   `_url` method anywhere in `app/`, they very likely
-      #   intend to call it (often Mastodon's pattern: a
-      #   controller's `private def page_url(page)` invoked
-      #   by a `link_to` in its own view). The core engine's
-      #   `call.undefined-method` rule still catches the case
-      #   where the receiver genuinely cannot see the method.
-      # - Ignores `def self.x` (singleton-method definitions) —
-      #   Rails helpers are instance methods on the helper
-      #   module; class-side `self.x` shapes are usually
-      #   internal utilities, not view helpers.
-      # - Filters the resulting set to names ending in `_path`
-      #   or `_url` (the dispatch surface the analyzer's rule
-      #   actually cares about). A helper whose name does not
-      #   end with either suffix is irrelevant to the rule's
-      #   false-positive surface, so excluding it costs nothing
-      #   and keeps the registered set focused.
+      # - Walks `def name(...)` declarations at the module / class top level. Nested `def` inside a method
+      #   body or a `define_method` macro is NOT extracted (the same reason `rigor-actionpack` is not the
+      #   canonical custom-helper source — metaprogrammed helpers are out of scope for a static scan).
+      # - **Visibility-agnostic.** A `private` / `protected` `def some_url` IS registered. The
+      #   `unknown-helper` rule is a project-wide name-presence check, not a visibility check — if the user
+      #   wrote a `_path` / `_url` method anywhere in `app/`, they very likely intend to call it (often
+      #   Mastodon's pattern: a controller's `private def page_url(page)` invoked by a `link_to` in its own
+      #   view). The core engine's `call.undefined-method` rule still catches the case where the receiver
+      #   genuinely cannot see the method.
+      # - Ignores `def self.x` (singleton-method definitions) — Rails helpers are instance methods on the
+      #   helper module; class-side `self.x` shapes are usually internal utilities, not view helpers.
+      # - Filters the resulting set to names ending in `_path` or `_url` (the dispatch surface the
+      #   analyzer's rule actually cares about). A helper whose name does not end with either suffix is
+      #   irrelevant to the rule's false-positive surface, so excluding it costs nothing and keeps the
+      #   registered set focused.
       #
       # Out of scope (intentional):
       #
-      # - Helpers defined via `define_method` or via macros like
-      #   `inheritance_traversed_helpers`. These would need
-      #   ADR-16 macro substrate or per-plugin custom recognizers.
-      # - Helpers inherited from gems (`Devise::Controllers::Helpers`,
-      #   `ViteRails::TagHelpers`, etc.). Those need their own
-      #   handling — Devise auto-routes are covered by the
-      #   companion `DeviseRoutes` generator; other gem-injected
-      #   helpers fall to ADR-25 plugin-contributed RBS or the
-      #   ADR-10 `dependencies.source_inference:` path.
+      # - Helpers defined via `define_method` or via macros like `inheritance_traversed_helpers`. These
+      #   would need ADR-16 macro substrate or per-plugin custom recognizers.
+      # - Helpers inherited from gems (`Devise::Controllers::Helpers`, `ViteRails::TagHelpers`, etc.).
+      #   Those need their own handling — Devise auto-routes are covered by the companion `DeviseRoutes`
+      #   generator; other gem-injected helpers fall to ADR-25 plugin-contributed RBS or the ADR-10
+      #   `dependencies.source_inference:` path.
       module HelperDiscoverer
         HELPER_SUFFIXES = [/_path\z/, /_url\z/].freeze
 
         module_function
 
-        # @param contents_per_path [Hash{String => String}]
-        #   file path → source text. The caller is responsible
-        #   for reading files (typically through the trusted
-        #   `IoBoundary` so cache invalidation works).
-        # @return [Set<String>] method names suitable for
-        #   inclusion in the `HelperTable`'s custom-helper set.
+        # @param contents_per_path [Hash{String => String}] file path → source text. The caller is
+        #   responsible for reading files (typically through the trusted `IoBoundary` so cache invalidation
+        #   works).
+        # @return [Set<String>] method names suitable for inclusion in the `HelperTable`'s custom-helper set.
         def discover(contents_per_path)
           names = []
           contents_per_path.each_value do |contents|
             names.concat(extract_from_contents(contents))
           rescue StandardError
-            # Skip any file whose AST walk explodes — discovery
-            # is best-effort and a parse failure in one helper
-            # file MUST NOT abort discovery for the rest. Other
-            # rules will still surface the parse failure on the
-            # affected file through the core pipeline.
+            # Skip any file whose AST walk explodes — discovery is best-effort and a parse failure in one
+            # helper file MUST NOT abort discovery for the rest. Other rules will still surface the parse
+            # failure on the affected file through the core pipeline.
             next
           end
           names.to_set
@@ -89,17 +67,9 @@ module Rigor
           walker.helper_names
         end
 
-        # Per-file AST walker. Tracks the current visibility
-        # mode (`:public` by default; `private` / `protected`
-        # calls flip the bit) so a `def` declared after a bare
-        # `private` is excluded.
-        #
-        # The walker is recursive into module / class bodies so
-        # `module UrlHelpers; module Routing; def foo_url; end;
-        # end; end` registers `foo_url`. It does NOT recurse
-        # into method bodies (a `def inside def` would be
-        # `define_method`-shaped, which we skip per the
-        # docstring).
+        # Per-file AST walker. The walker is recursive into module / class bodies so `module UrlHelpers;
+        # module Routing; def foo_url; end; end; end` registers `foo_url`. It does NOT recurse into method
+        # bodies (a `def inside def` would be `define_method`-shaped, which we skip per the docstring).
         class ModuleBodyWalker
           attr_reader :helper_names
 
@@ -134,11 +104,9 @@ module Rigor
           def visit_statements(body)
             return if body.nil?
 
-            # Visibility tracking is intentionally absent — see
-            # the "visibility-agnostic" point in the module
-            # docstring. A `private def page_url(page)` inside
-            # a controller IS registered so a caller in the
-            # paired view does not false-fire `unknown-helper`.
+            # Visibility tracking is intentionally absent — see the "visibility-agnostic" point in the
+            # module docstring. A `private def page_url(page)` inside a controller IS registered so a
+            # caller in the paired view does not false-fire `unknown-helper`.
             statements_of(body).each do |stmt|
               case stmt
               when Prism::DefNode