rigortype 0.2.8 → 0.3.0

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

@@ -122,6 +122,16 @@ module Rigor
         carried_type(receiver_type, call_node.name)
       end
 
+      # ADR-88 WD1 — the `dynamic_return` contribution is a PURE STRUCTURAL projection of the receiver's own
+      # carrier type args (`Result[T, E]#unwrap → T`), computed per call from the receiver type the engine
+      # already resolved; it reads no cross-file catalog. (The `Enum` nested-class emission rides the ADR-16
+      # macro substrate / synthetic-method scanner, a separate pre-pass, not this `dynamic_return`.) A stable
+      # sentinel declares "no cross-file fact surface", keeping the plugin incremental-capable; the
+      # `--verify-incremental` gate backstops the claim.
+      def incremental_state_fingerprint
+        "structural-carriers"
+      end
+
       private
 
       # @return [Rigor::Type, nil] the receiver's inferred type, or nil when the engine raises on a synthetic

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

@@ -62,6 +62,17 @@ module Rigor
       narrowing_facts methods: AssertionAnalyzer::SUPPORTED_METHODS do |call_node, scope|
         AssertionAnalyzer.contribution_for(call_node, environment: scope&.environment)&.post_return_facts
       end
+
+      # ADR-88 WD1 — the narrowing facts this plugin contributes are derived purely from each assertion call's
+      # own AST at its call site (`assert_kind_of(String, x)` ⇒ `x` is `String` on the continuation); there is
+      # no cross-file catalog a cached diagnostic could depend on. A change to a file's assertions changes that
+      # file's own content (re-analysed by the incremental graph already). A stable sentinel declares "no
+      # cross-file fact surface", keeping the plugin incremental-capable (a contributing plugin with NO
+      # fact / producer / hook makes the incremental snapshot un-reusable every run); `--verify-incremental`
+      # backstops the claim.
+      def incremental_state_fingerprint
+        "per-file-assertions"
+      end
     end
 
     Rigor::Plugin.register(Minitest)

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/policy_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "policy_index"
@@ -69,7 +71,7 @@ module Rigor
           when Prism::ClassNode then visit_class(node, lexical_path, &)
           when Prism::ModuleNode then visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_policies(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_policies(child, lexical_path, &) }
           end
         end
 

data/plugins/rigor-rails/lib/rigor-rails.rb

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
-# Convenience entry point. `require "rigor-rails"` requires every Tier 1+2 Rails ecosystem plugin in one go,
-# so projects that prefer a single require statement (some `spec_helper` patterns, ad-hoc scripts) do not
-# have to list seven require lines.
+# The Tier 1+2 Rails set, as a single require. Requiring this file registers every member class with
+# `Rigor::Plugin`; the loader's lookup phase then finds them by id when `.rigor.yml` enumerates them.
 #
-# Note: requiring this entry point does NOT mark every plugin as active. The Rigor plugin loader walks
-# `.rigor.yml`'s `plugins:` list and instantiates only the plugins enumerated there. This is per ADR-12
-# WD1's "Gemfile-convenience meta-gem" pattern — users still control which plugins participate in analysis
-# via `.rigor.yml`.
+# UNWIRED — this entry point has no supported use today, and is kept deliberately (ADR-96 WD5) rather
+# than removed. It was ADR-12 WD1's "Gemfile-convenience meta-gem": each plugin was to be its own gem, and
+# `gem "rigor-rails"` was to pull the Rails set into a project's Gemfile in one line. Commit `9769f5fa`
+# dropped the per-plugin gemspecs and ADR-31 settled distribution on the single bundled `rigortype` gem, so
+# there is no `rigor-rails` gem to add to a Gemfile — and `plugins: [rigor-rails]` is rejected by the
+# loader, which requires the members to be enumerated (or one selected with an explicit `id:`).
 #
-# Sub-plugins ARE registered with `Rigor::Plugin` when this file loads (each gem's entry point side-effects
-# a `Plugin.register` call); the loader's lookup phase finds them by id when listed.
-#
-# Adding the gem to a project's Gemfile without listing any plugin in `.rigor.yml` is harmless: the requires
-# happen on `Bundler.require`, but no plugin's `init` / `prepare` / hooks run.
+# ADR-96 WD3 proposes the role this file would fill: `plugins: [rigor-rails]` activating those members
+# whose `target_gems:` are actually in the project's `Gemfile.lock`. If that is rejected, ADR-60 WD1's
+# never-wired-surface criterion applies and this directory goes.
 
 require "rigor-rails-routes"
 require "rigor-rails-i18n"

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "rigor/source/node_children"
+
+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.rigor_each_child { |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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -87,7 +89,7 @@ module Rigor
           def visit_program_children(node)
             return unless node.respond_to?(:compact_child_nodes)
 
-            node.compact_child_nodes.each do |child|
+            node.rigor_each_child do |child|
               case child
               when Prism::ModuleNode, Prism::ClassNode
                 visit_module_or_class(child)

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

@@ -36,7 +36,11 @@ module Rigor
         #   (`<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: [])
+        # @param grape_prefixes [Enumerable<String>] helper-name prefixes generated by `grape-path-helpers`
+        #   (`"api_v4"`), composed by {GrapeApiDiscoverer} from the project's own `prefix` / `version`
+        #   declarations. The names beyond the prefix come from grape's runtime route table and cannot be
+        #   enumerated statically, so the namespace is open — same contract as the OmniAuth family above.
+        def initialize(entries, custom_helpers: [], devise_resources: [], grape_prefixes: [])
           @entries = entries.freeze
           # Multimap: a single helper name can map to multiple entries when an uncountable-noun resource
           # registers both an arity-0 index helper and an arity-1 show helper under the same `news_path`
@@ -45,6 +49,7 @@ module Rigor
           @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
+          @grape_prefixes = grape_prefixes.to_set(&:to_s).freeze
           freeze
         end
 
@@ -67,10 +72,23 @@ module Rigor
           name = helper_name.to_s
           return true if @by_name.key?(name)
           return true if @custom_helpers.include?(name)
+          return true if grape_match?(name)
 
           omniauth_match?(name)
         end
 
+        # `<prefix>_<anything>_path` for a prefix the project's grape API declares. Only the `_path` suffix
+        # matches: `grape-path-helpers` defines no `_url` helper (its `method_missing` returns `super` unless
+        # the name ends with `_path`), so `api_v4_groups_url` is a genuine unknown helper and still fires.
+        # The bare `<prefix>_path` (the namespace root) matches too.
+        def grape_match?(name)
+          return false if @grape_prefixes.empty?
+          return false unless name.end_with?("_path")
+
+          stem = name.delete_suffix("_path")
+          @grape_prefixes.any? { |prefix| stem == prefix || stem.start_with?("#{prefix}_") }
+        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

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -56,9 +58,11 @@ module Rigor
         #   draw partial from `config/routes/name.rb`. Returns file contents
         #   or nil when the file is absent.
         # @return [HelperTable]
-        def parse(contents, file_reader: nil, custom_helpers: [])
+        def parse(contents, file_reader: nil, custom_helpers: [], grape_prefixes: [])
           parse_result = Prism.parse(contents)
-          return HelperTable.new([], custom_helpers: custom_helpers) unless parse_result.errors.empty?
+          unless parse_result.errors.empty?
+            return HelperTable.new([], custom_helpers: custom_helpers, grape_prefixes: grape_prefixes)
+          end
 
           context = Context.new(file_reader: file_reader)
           interpret(parse_result.value, context)
@@ -80,7 +84,8 @@ module Rigor
               )
             ]
           end
-          HelperTable.new(paired, custom_helpers: custom_helpers, devise_resources: context.devise_resources)
+          HelperTable.new(paired, custom_helpers: custom_helpers, devise_resources: context.devise_resources,
+                                  grape_prefixes: grape_prefixes)
         end
 
         # For every registered alias rule `(from_str, to_str, arity_delta)`, find every existing entry whose
@@ -368,7 +373,7 @@ module Rigor
           when Prism::CallNode
             interpret_call(node, context)
           else
-            node.compact_child_nodes.each { |child| interpret(child, context) }
+            node.rigor_each_child { |child| interpret(child, context) }
           end
         end
 
@@ -523,7 +528,7 @@ module Rigor
           return unless node.is_a?(Prism::Node)
 
           yield node
-          node.compact_child_nodes.each { |child| walk_for_alias_pattern(child, &) }
+          node.rigor_each_child { |child| walk_for_alias_pattern(child, &) }
         end
 
         def first_block_parameter_name(block_node)
@@ -542,7 +547,7 @@ module Rigor
           body = node.block&.body
           return if body.nil?
 
-          body.compact_child_nodes.each { |child| interpret(child, context) }
+          body.rigor_each_child { |child| interpret(child, context) }
         end
 
         def handle_namespace(node, context)
@@ -622,7 +627,7 @@ module Rigor
           return [] if body.nil?
 
           skips = []
-          body.compact_child_nodes.each do |child|
+          body.rigor_each_child do |child|
             next unless child.is_a?(Prism::CallNode) && child.name == :skip_controllers
             next if child.receiver
 
@@ -745,7 +750,7 @@ module Rigor
             body = context.concern_body(concern_name)
             next if body.nil?
 
-            body.compact_child_nodes.each { |child| interpret(child, context) }
+            body.rigor_each_child { |child| interpret(child, context) }
           end
         end
 
@@ -808,6 +813,12 @@ module Rigor
           # String key in the trailing keyword/options hash (its value is the `controller#action`). Without
           # this, the arity check underestimates because the placeholder count comes from a nil path.
           path = string_argument(node, 0) || hashrocket_path_key(node)
+          # `get :activity` inside a `scope(as: :user)` — NOT a resources / member / collection block (that
+          # shape returned early above), so the symbol is both the path segment (`/activity`) and the action
+          # name. Rails composes `<scope_as>_activity_path`. Fall the symbol back into the path so the
+          # name-and-arity derivation below picks it up; without it the route registered nothing and every
+          # `user_activity_path` call read as `unknown-helper`.
+          path ||= symbol_action_path(node)
           as_name = keyword_symbol(node, :as)
           return if as_name.nil? && path.nil?
 
@@ -844,6 +855,14 @@ module Rigor
           end
         end
 
+        # `/activity` for a bare `get :activity` first-arg symbol (used as both path and action name), else
+        # nil. Only reached outside a resources / member / collection block — the symbol-shorthand there is
+        # already handled as a member/collection action upstream.
+        def symbol_action_path(node)
+          symbol = symbol_argument(node, 0)
+          symbol && "/#{symbol}"
+        end
+
         # Builds the helper name for an explicit `get` / `post` / `match` route. Rails uses two distinct
         # shapes:
         #
@@ -879,12 +898,24 @@ module Rigor
 
           first_arg = node.arguments&.arguments&.first
           return true if first_arg.is_a?(Prism::SymbolNode)
-
-          # A plain action-name string with no `/` or `:` — treat it as if it were a symbol (`get 'report'`
-          # == `get :report` inside member/collection block).
-          first_arg.is_a?(Prism::StringNode) &&
-            !first_arg.unescaped.include?("/") &&
-            !first_arg.unescaped.include?(":")
+          return false unless first_arg.is_a?(Prism::StringNode)
+
+          path = first_arg.unescaped
+          # A dynamic segment (`get 'foo/:id'`) is a real path, not a plain action name — leave it to the
+          # generic explicit-route handler.
+          return false if path.include?(":")
+
+          # A bare `get '/'` (or `''`) inside a `collection do` block is the collection root, not an action
+          # shorthand — Rails names it after the enclosing resource, not `<empty>_<plural>_path`. An empty
+          # normalized action name means "not a shorthand"; fall through to the generic handler.
+          return false if path.delete_prefix("/").tr("/", "_").empty?
+
+          # A single-segment string is an action name in any resource context (`get 'report'` == `get
+          # :report`). A MULTI-segment static path (`get 'granular/new'`) is an action too, but only inside
+          # an explicit `member do` / `collection do` block, where Rails' `Mapper.normalize_name` maps the
+          # slashes to underscores (`granular_new_<scope>_<plural>_path`). Outside such a block (a bare
+          # `resources` scope) a multi-segment path is a nested custom route, so keep the generic handler.
+          !path.include?("/") || !context.innermost_action_block.nil?
         end
 
         # Generates the member / collection action helper.
@@ -893,8 +924,10 @@ module Rigor
         # Collection: `<action>_<plural_helper_prefix>path`,
         #   arity = parent_segment_count - 1 (no `:id` segment; the collection URL is /<resource>/<action>).
         def register_member_collection_action(node, context)
+          # A multi-segment string action (`get 'granular/new'` in a `collection do` block) is named by
+          # Rails via `normalize_name` — leading slash stripped, remaining slashes → underscores.
           action_name = symbol_argument(node, 0)&.to_s ||
-                        string_argument(node, 0).to_s
+                        string_argument(node, 0).to_s.delete_prefix("/").tr("/", "_")
           frame = context.innermost_action_block
           # No `member do` / `collection do` wrapper but we're inside a resources block — Rails defaults a
           # bare `<verb> :symbol` inside resources to a MEMBER action (e.g. `get :preview` →

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

@@ -5,6 +5,7 @@ require "rigor/plugin"
 require_relative "rails_routes/helper_table"
 require_relative "rails_routes/routes_parser"
 require_relative "rails_routes/helper_discoverer"
+require_relative "rails_routes/grape_api_discoverer"
 require_relative "rails_routes/analyzer"
 
 module Rigor
@@ -34,6 +35,11 @@ module Rigor
     #         config:
     #           routes_file: config/routes.rb   # default; optional
     #
+    # A project mounting a Grape API keeps its `grape-path-helpers` helpers (`api_v4_groups_badges_path`)
+    # out of `unknown-helper`: those names come from grape's runtime route table, so {GrapeApiDiscoverer}
+    # recognises the namespace their `prefix` / `version` declarations open rather than enumerating names
+    # it cannot know.
+    #
     # ## Limitations (v0.1.0)
     #
     # - `scope :path:` / `scope :module:` / `scope :as:` are not interpreted — helpers nested inside these
@@ -50,8 +56,10 @@ module Rigor
         # ':project_id', as: :project)` — path read from the `:path` keyword, not only from the positional
         # first arg; (c) detection of iterative `direct(name.sub(FROM, TO)) do ... end` alias-generation
         # idiom — generates `<TO>_*` aliases for every registered `<FROM>_*` helper. GitLab uses this to
-        # shorten `namespace_project_*` → `project_*`.
-        version: "0.27.0",
+        # shorten `namespace_project_*` → `project_*`. Bumped 2026-07-10 — recognises the open helper
+        # namespace `grape-path-helpers` generates (`api_v4_*_path`), grounded in the project's own Grape
+        # `prefix` / `version` declarations (see {GrapeApiDiscoverer}).
+        version: "0.28.0",
         description: "Validates Rails route-helper calls against `config/routes.rb`.",
         config_schema: {
           "routes_file" => { kind: :string, default: "config/routes.rb" },
@@ -63,7 +71,12 @@ module Rigor
           # `app/serializers`, `app/presenters`, `app/decorators`, not only `app/helpers/`. Walking the
           # whole tree is the honest answer to "does this `_path` / `_url` name exist anywhere in the
           # project?"; the cost is a one-time Prism parse per file at startup, which is bounded.
-          "helper_paths" => { kind: :array, default: ["app"] }
+          "helper_paths" => { kind: :array, default: ["app"] },
+          # `grape_api_paths` — the directories scanned for Grape API classes, whose `prefix` / `version`
+          # declarations ground the open `api_v4_*_path` helper namespace `grape-path-helpers` generates
+          # (see {GrapeApiDiscoverer}). Defaults cover the two conventional homes; a project with no grape
+          # API declares no prefixes and nothing changes for it.
+          "grape_api_paths" => { kind: :array, default: ["lib/api", "app/api"] }
         },
         produces: [:helper_table]
       )
@@ -73,11 +86,12 @@ module Rigor
       # routes-file edits.
       #
       # Passes a `file_reader` lambda so the parser can follow `draw(:admin)` → `config/routes/admin.rb`
-      # partials. `watch:` (ADR-60 WD3) covers every `.rb` under `helper_paths:` so ADDING a helper file
-      # invalidates the table — the producer's own in-block reads (the routes file + the partials it
-      # follows via `draw`) are captured post-compute, but a brand-new helper file the prior run never read
-      # would otherwise read as fresh.
-      producer :helper_table, watch: -> { @helper_paths.map { |dir| [dir, "**/*.rb"] } } do |_params|
+      # partials. `watch:` (ADR-60 WD3) covers every `.rb` under `helper_paths:` and `grape_api_paths:` so
+      # ADDING a helper file — or a Grape API whose `version` declaration opens a new namespace —
+      # invalidates the table. The producer's own in-block reads (the routes file + the partials it follows
+      # via `draw`) are captured post-compute, but a brand-new file the prior run never read would otherwise
+      # read as fresh.
+      producer :helper_table, watch: -> { (@helper_paths + @grape_api_paths).map { |dir| [dir, "**/*.rb"] } } do |_p|
         routes_dir = "#{File.dirname(@routes_file)}/routes"
         file_reader = lambda do |name|
           io_boundary.read_file("#{routes_dir}/#{name}")
@@ -85,13 +99,14 @@ module Rigor
           nil
         end
         contents = io_boundary.read_file(@routes_file)
-        custom_helpers = discover_custom_helpers
-        RoutesParser.parse(contents, file_reader: file_reader, custom_helpers: custom_helpers)
+        RoutesParser.parse(contents, file_reader: file_reader, custom_helpers: discover_custom_helpers,
+                                     grape_prefixes: discover_grape_prefixes)
       end
 
       def init(_services)
         @routes_file = config.fetch("routes_file")
         @helper_paths = Array(config.fetch("helper_paths")).map(&:to_s)
+        @grape_api_paths = Array(config.fetch("grape_api_paths")).map(&:to_s)
         @helper_table = nil
         @helper_table_built = false
         @load_error = nil
@@ -112,8 +127,23 @@ module Rigor
         HelperDiscoverer.discover(contents_per_path)
       end
 
-      def each_helper_file(&)
-        @helper_paths.each do |dir|
+      # Walks `grape_api_paths:` through the trusted `IoBoundary` and returns the helper-name prefixes the
+      # project's Grape API classes generate (`["api_v3", "api_v4"]`). Empty for a project with no grape API,
+      # which leaves `unknown-helper` behaviour exactly as it was.
+      def discover_grape_prefixes
+        contents_per_path = {}
+        each_ruby_file(@grape_api_paths) do |path|
+          contents_per_path[path] = io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          next
+        end
+        GrapeApiDiscoverer.discover(contents_per_path)
+      end
+
+      def each_helper_file(&) = each_ruby_file(@helper_paths, &)
+
+      def each_ruby_file(dirs, &)
+        dirs.each do |dir|
           absolute = File.expand_path(dir)
           next unless File.directory?(absolute)