rigortype 0.1.11 → 0.1.12

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+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).
+      #
+      # 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.
+      #
+      # 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.
+      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.
+        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.
+            next
+          end
+          names.to_set
+        end
+
+        def extract_from_contents(contents)
+          parse_result = Prism.parse(contents)
+          return [] unless parse_result.errors.empty?
+
+          walker = ModuleBodyWalker.new
+          walker.walk(parse_result.value)
+          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).
+        class ModuleBodyWalker
+          attr_reader :helper_names
+
+          def initialize
+            @helper_names = []
+          end
+
+          def walk(node)
+            visit_statements(node) if node.is_a?(Prism::ProgramNode)
+            visit_program_children(node)
+          end
+
+          private
+
+          def visit_program_children(node)
+            return unless node.respond_to?(:compact_child_nodes)
+
+            node.compact_child_nodes.each do |child|
+              case child
+              when Prism::ModuleNode, Prism::ClassNode
+                visit_module_or_class(child)
+              when Prism::ProgramNode, Prism::StatementsNode
+                visit_program_children(child)
+              end
+            end
+          end
+
+          def visit_module_or_class(node)
+            visit_statements(node.body)
+          end
+
+          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`.
+            statements_of(body).each do |stmt|
+              case stmt
+              when Prism::DefNode
+                record_helper(stmt)
+              when Prism::ModuleNode, Prism::ClassNode
+                visit_module_or_class(stmt)
+              when Prism::StatementsNode
+                visit_statements(stmt)
+              end
+            end
+          end
+
+          def statements_of(node)
+            case node
+            when Prism::StatementsNode then node.body
+            when Prism::BeginNode      then statements_of(node.statements)
+            else [node]
+            end
+          end
+
+          def record_helper(def_node)
+            # Skip singleton methods (`def self.x`).
+            return if def_node.receiver
+
+            name = def_node.name.to_s
+            return unless HELPER_SUFFIXES.any? { |suffix| name.match?(suffix) }
+
+            @helper_names << name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "devise_routes"
+require_relative "doorkeeper_routes"
+
 module Rigor
   module Plugin
     class RailsRoutes < Rigor::Plugin::Base
@@ -30,11 +33,27 @@ module Rigor
       class HelperTable
         Entry = Data.define(:name, :arity, :path, :http_method, :action)
 
-        attr_reader :entries
+        attr_reader :entries, :custom_helpers, :devise_resources
 
         # @param entries [Array<Entry>] freshly built; the
         #   factory below is the canonical construction path.
-        def initialize(entries)
+        # @param custom_helpers [Enumerable<String>] names of
+        #   project-defined helper methods (typically pulled
+        #   from `app/helpers/**/*.rb` by
+        #   {HelperDiscoverer}) that the analyzer should treat
+        #   as known — they do NOT correspond to a route but
+        #   their presence MUST NOT fire `unknown-helper`. No
+        #   arity / path metadata is recorded; the analyzer
+        #   skips the route-side checks for these names.
+        # @param devise_resources [Enumerable<String>] resource
+        #   names declared via `devise_for :resource` (already
+        #   singularised, e.g. `"user"`). Used to recognise the
+        #   dynamic OmniAuth helper family
+        #   (`<resource>_<provider>_omniauth_(authorize|callback)_(path|url)`)
+        #   whose provider segment is supplied at runtime — no
+        #   per-name entry is registered for them but they MUST
+        #   NOT fire `unknown-helper` either.
+        def initialize(entries, custom_helpers: [], devise_resources: [])
           @entries = entries.freeze
           # Multimap: a single helper name can map to multiple
           # entries when an uncountable-noun resource registers
@@ -43,6 +62,8 @@ module Rigor
           # returns the first entry (preserving the previous
           # API); `accepts_arity?` checks against every entry.
           @by_name = entries.group_by(&:name).transform_values(&:freeze).freeze
+          @custom_helpers = custom_helpers.to_set.freeze
+          @devise_resources = devise_resources.to_set(&:to_s).freeze
           freeze
         end
 
@@ -59,10 +80,50 @@ module Rigor
           @by_name.key?(helper_name.to_s)
         end
 
+        # True when `helper_name` is either a registered route
+        # helper, a discovered project-defined custom helper,
+        # OR a dynamic OmniAuth-shaped helper for one of the
+        # declared `devise_for` resources. The
+        # `unknown-helper` rule consults this predicate to
+        # decide whether to fire — `known?` alone misses
+        # custom helpers and OmniAuth providers, which would
+        # then false-fire on canonical Rails-app patterns.
+        def recognised?(helper_name)
+          name = helper_name.to_s
+          return true if @by_name.key?(name)
+          return true if @custom_helpers.include?(name)
+
+          omniauth_match?(name)
+        end
+
+        # `<resource>_<provider>_omniauth_(authorize|callback)_(path|url)` — when
+        # `<resource>` matches a declared `devise_for` resource
+        # the helper is dynamic-provider Devise OmniAuth. The
+        # provider segment is opaque to a static parser, so we
+        # accept any non-empty token between the resource and
+        # the omniauth suffix.
+        def omniauth_match?(name)
+          return false if @devise_resources.empty?
+
+          DeviseRoutes::OMNIAUTH_SUFFIXES.any? do |suffix|
+            next false unless name.end_with?(suffix)
+
+            stem = name.delete_suffix(suffix)
+            @devise_resources.any? do |resource|
+              stem.start_with?("#{resource}_") && stem.length > resource.length + 1
+            end
+          end
+        end
+
         # @return [Boolean] true when any entry under this
         #   helper name accepts the given positional arity.
+        #
+        # Rails helpers have the signature `helper(*segments, options = {})`,
+        # so `expected + 1` is always valid — the extra argument is treated
+        # as a query-params/options hash (e.g. `users_path(page: 2)` or
+        # `user_path(@u, pagination_params(...))`).
         def accepts_arity?(helper_name, arity)
-          (@by_name[helper_name.to_s] || []).any? { |entry| entry.arity == arity }
+          (@by_name[helper_name.to_s] || []).any? { |entry| entry.arity == arity || entry.arity + 1 == arity }
         end
 
         # @return [Array<Integer>] all accepted positional