rigortype 0.2.7 → 0.2.9

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

@@ -5,17 +5,17 @@ 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
   module Plugin
-    # rigor-rails-routes — validates Rails route-helper calls
-    # (`users_path`, `edit_user_path(@user)`, …) against the
-    # project's `config/routes.rb`.
+    # rigor-rails-routes — validates Rails route-helper calls (`users_path`, `edit_user_path(@user)`, …)
+    # against the project's `config/routes.rb`.
     #
     # Tier 1A of the [Rails plugins roadmap](../../../../docs/design/20260508-rails-plugins-roadmap.md).
-    # Statically interprets the routes DSL via Prism — no
-    # `rails` runtime dependency. Recognised v0.1.0 surface:
+    # Statically interprets the routes DSL via Prism — no `rails` runtime dependency. Recognised v0.1.0
+    # surface:
     #
     # - `Rails.application.routes.draw do ... end`
     # - `resources :name [, only: [...] | except: [...]]`
@@ -25,10 +25,8 @@ module Rigor
     # - One level of `namespace :foo do ... end`
     # - One level of nested `resources`
     #
-    # The plugin publishes its parsed `:helper_table` through
-    # the ADR-9 cross-plugin fact store; `rigor-actionpack`
-    # Phase 4 consumes it for route-helper validation in
-    # controller code.
+    # The plugin publishes its parsed `:helper_table` through the ADR-9 cross-plugin fact store;
+    # `rigor-actionpack` Phase 4 consumes it for route-helper validation in controller code.
     #
     # ## Configuration
     #
@@ -37,69 +35,63 @@ 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
+    # - `scope :path:` / `scope :module:` / `scope :as:` are not interpreted — helpers nested inside these
     #   constructs are silently skipped.
-    # - Constraints / format restrictions / mountable
-    #   engines are out of scope.
-    # - The English inflector is intentionally tiny: it
-    #   handles `posts` ↔ `post`, `users` ↔ `user`,
-    #   `categories` ↔ `category`, `boxes` ↔ `box`. Custom
-    #   inflections (`fish` ↔ `fish`, `child` ↔ `children`)
-    #   are out of scope; users who need them ship a hand-
-    #   written RBS for the affected helper.
+    # - Constraints / format restrictions / mountable engines are out of scope.
+    # - The English inflector is intentionally tiny: it handles `posts` ↔ `post`, `users` ↔ `user`,
+    #   `categories` ↔ `category`, `boxes` ↔ `box`. Custom inflections (`fish` ↔ `fish`, `child` ↔
+    #   `children`) are out of scope; users who need them ship a hand-written RBS for the affected helper.
     class RailsRoutes < Rigor::Plugin::Base
       manifest(
         id: "rails-routes",
-        # Bumped 2026-05-28 — GitLab FOSS sweep adds: (a)
-        # `draw_all :name` support (action_dispatch-draw_all
-        # gem; single-file load semantics matching `draw :name`);
-        # (b) keyword-style `scope(path: ':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",
+        # Bumped 2026-05-28 — GitLab FOSS sweep adds: (a) `draw_all :name` support (action_dispatch-draw_all
+        # gem; single-file load semantics matching `draw :name`); (b) keyword-style `scope(path:
+        # ':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_*`. 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" },
-          # `helper_paths` — the directories `HelperDiscoverer` walks
-          # for project-defined `*_path` / `*_url` methods. Default to
-          # the whole `app/` tree — the suffix filter inside the
-          # discoverer keeps the registered set tight, and real-world
-          # Rails apps routinely keep URL builders under
-          # `app/controllers` (private `def page_url`, `def callback_url`
-          # shapes), `app/lib` (Mastodon's
-          # `TranslationService::DeepL#base_url`), `app/services`
-          # (`SoftwareUpdateCheckService#api_url`), `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` — the directories `HelperDiscoverer` walks for project-defined `*_path` / `*_url`
+          # methods. Default to the whole `app/` tree — the suffix filter inside the discoverer keeps the
+          # registered set tight, and real-world Rails apps routinely keep URL builders under
+          # `app/controllers` (private `def page_url`, `def callback_url` shapes), `app/lib` (Mastodon's
+          # `TranslationService::DeepL#base_url`), `app/services` (`SoftwareUpdateCheckService#api_url`),
+          # `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"] },
+          # `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]
       )
 
-      # Cached producer — reads `config/routes.rb` through
-      # the trusted `IoBoundary` and parses through
-      # {RoutesParser}. The descriptor's auto-collected
-      # `FileEntry` digest invalidates the cache on routes-
-      # file edits.
+      # Cached producer — reads `config/routes.rb` through the trusted `IoBoundary` and parses through
+      # {RoutesParser}. The descriptor's auto-collected `FileEntry` digest invalidates the cache on
+      # 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|
+      # 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:` 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}")
@@ -107,26 +99,24 @@ 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
       end
 
-      # Walks every configured `helper_paths:` directory
-      # through the trusted `IoBoundary` and returns the set
-      # of project-defined `*_path` / `*_url` method names
-      # for {HelperDiscoverer}. Each file digest is captured
-      # by the boundary so editing a helper file invalidates
-      # the `:helper_table` cache automatically. Returns the
-      # empty set when nothing under `helper_paths:` exists —
-      # the routes table still works.
+      # Walks every configured `helper_paths:` directory through the trusted `IoBoundary` and returns the
+      # set of project-defined `*_path` / `*_url` method names for {HelperDiscoverer}. Each file digest is
+      # captured by the boundary so editing a helper file invalidates the `:helper_table` cache
+      # automatically. Returns the empty set when nothing under `helper_paths:` exists — the routes table
+      # still works.
       def discover_custom_helpers
         contents_per_path = {}
         each_helper_file do |path|
@@ -137,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)
 
@@ -146,8 +151,7 @@ module Rigor
         end
       end
 
-      # Publishes the parsed table to the cross-plugin fact
-      # store; `rigor-actionpack` Phase 4 reads it via
+      # Publishes the parsed table to the cross-plugin fact store; `rigor-actionpack` Phase 4 reads it via
       # `services.fact_store.read`.
       def prepare(services)
         table = helper_table_or_nil
@@ -160,10 +164,9 @@ module Rigor
         )
       end
 
-      # File-level only: the once-per-run load-error emission. Per-call
-      # helper validation runs over the engine-owned walk via the
-      # node_rule below (ADR-37), with the same-file `shadowing` set
-      # built once as the node-rule file context.
+      # File-level only: the once-per-run load-error emission. Per-call helper validation runs over the
+      # engine-owned walk via the node_rule below (ADR-37), with the same-file `shadowing` set built once
+      # as the node-rule file context.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         table = helper_table_or_nil
         if table.nil? && @load_error
@@ -191,31 +194,23 @@ module Rigor
 
       private
 
-      # The load-error path used to emit the same warning on
-      # every analyzed file in the project. On large monorepos
-      # (Mastodon: 1,302 files; Solidus: ~1,000 files) and on
-      # legacy projects without a top-level `config/routes.rb`,
-      # this multiplied a single root cause into 1,000+
-      # identical diagnostics. The error is project-global —
-      # report it once per run.
+      # The load-error path used to emit the same warning on every analyzed file in the project. On large
+      # monorepos (Mastodon: 1,302 files; Solidus: ~1,000 files) and on legacy projects without a top-level
+      # `config/routes.rb`, this multiplied a single root cause into 1,000+ identical diagnostics. The
+      # error is project-global — report it once per run.
 
       def helper_table_or_nil
-        # Memoise the build *attempt*, not just a truthy result: when the
-        # routes file is missing or unparseable the table is nil, and the
-        # old `return @helper_table if @helper_table` re-ran the whole
-        # read-and-parse on every call. The engine consults this per
-        # route-helper dispatch, so a nil table meant re-reading (and, on
-        # a real project, re-parsing) `config/routes.rb` tens of thousands
-        # of times per run. The result — nil included — is stable for the
-        # run, so one attempt is correct.
+        # Memoise the build *attempt*, not just a truthy result: when the routes file is missing or
+        # unparseable the table is nil, and the old `return @helper_table if @helper_table` re-ran the
+        # whole read-and-parse on every call. The engine consults this per route-helper dispatch, so a nil
+        # table meant re-reading (and, on a real project, re-parsing) `config/routes.rb` tens of thousands
+        # of times per run. The result — nil included — is stable for the run, so one attempt is correct.
         return @helper_table if @helper_table_built
 
         @helper_table_built = true
-        # ADR-60 WD3 record-and-validate: the producer's in-block reads
-        # (the routes file + the partials it follows) are captured into
-        # the dependency descriptor AFTER the block runs, and the
-        # producer's `watch:` covers helper-file additions — so no
-        # priming read is needed here.
+        # ADR-60 WD3 record-and-validate: the producer's in-block reads (the routes file + the partials it
+        # follows) are captured into the dependency descriptor AFTER the block runs, and the producer's
+        # `watch:` covers helper-file additions — so no priming read is needed here.
         @helper_table = cache_for(:helper_table, params: {}).call
       rescue Plugin::AccessDeniedError => e
         @load_error = "rigor-rails-routes: #{e.message}"

data/plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb

@@ -4,24 +4,18 @@ require "rigor/plugin"
 
 # ADR-32 — bundled `rigor-rbs-inline` plugin.
 #
-# Synthesises RBS from project Ruby files that carry
-# rbs-inline-shaped comments (`#: () -> T`, `# @rbs name: T`,
-# `# @rbs return: T`, attribute `#:`, …) and contributes the
-# result to the analysis environment through the
-# `source_rbs_synthesizer:` manifest hook.
+# Synthesises RBS from project Ruby files that carry rbs-inline-shaped comments (`#: () -> T`, `# @rbs
+# name: T`, `# @rbs return: T`, attribute `#:`, …) and contributes the result to the analysis environment
+# through the `source_rbs_synthesizer:` manifest hook.
 #
-# By default (WD2) only files starting with the upstream
-# `# rbs_inline: enabled` magic comment are processed; a host
-# context can flip this off by setting `require_magic_comment:
-# false` in the plugin config (WD10).
+# By default (WD2) only files starting with the upstream `# rbs_inline: enabled` magic comment are
+# processed; a host context can flip this off by setting `require_magic_comment: false` in the plugin
+# config (WD10).
 module Rigor
   module Plugin
-    # The plugin gem requires `rbs/inline` at load time; without
-    # the upstream library the synthesizer can't do its job.
-    # Wrapped in a begin/rescue so the analyzer still loads if
-    # the user activated this plugin without installing the
-    # `rbs-inline` gem (loud-on-activation, fail-soft to no
-    # contribution).
+    # The plugin gem requires `rbs/inline` at load time; without the upstream library the synthesizer can't
+    # do its job. Wrapped in a begin/rescue so the analyzer still loads if the user activated this plugin
+    # without installing the `rbs-inline` gem (loud-on-activation, fail-soft to no contribution).
     begin
       require "prism"
       require "rbs/inline"
@@ -37,18 +31,13 @@ module Rigor
     end
 
     class RbsInline < Rigor::Plugin::Base
-      # Synthesizer callable invoked once per project Ruby
-      # source file by `Environment.for_project` at env-build
-      # time. Returns the synthesised RBS source as a String,
-      # or `nil` when the file contributes nothing (no magic
-      # comment in the default mode, empty annotation set,
-      # parse error per WD6).
+      # Synthesizer callable invoked once per project Ruby source file by `Environment.for_project` at
+      # env-build time. Returns the synthesised RBS source as a String, or `nil` when the file contributes
+      # nothing (no magic comment in the default mode, empty annotation set, parse error per WD6).
       class Synthesizer
-        # @param require_magic_comment [Boolean] when `true`
-        #   (the default, WD2), only files with
-        #   `# rbs_inline: enabled` at the top are processed.
-        #   When `false` (WD10 host-context override), every
-        #   file is treated as if it carried the magic comment.
+        # @param require_magic_comment [Boolean] when `true` (the default, WD2), only files with
+        #   `# rbs_inline: enabled` at the top are processed. When `false` (WD10 host-context override),
+        #   every file is treated as if it carried the magic comment.
         def initialize(require_magic_comment:)
           @require_magic_comment = require_magic_comment
           freeze
@@ -57,8 +46,7 @@ module Rigor
         # Return value contract:
         # - `String` (non-empty)         → successful synthesis
         # - `nil`                        → no contribution
-        # - `[:error, message_string]`   → parse failed, surface
-        #   info diagnostic per ADR-32 WD6
+        # - `[:error, message_string]`   → parse failed, surface info diagnostic per ADR-32 WD6
         def call(source_file_path)
           return nil unless RBS_INLINE_AVAILABLE
           return nil unless File.file?(source_file_path)
@@ -67,10 +55,8 @@ module Rigor
           return nil if source.empty?
 
           result = ::Prism.parse(source)
-          # `opt_in: true` is rbs-inline's "require the magic
-          # comment" mode (per upstream parser.rb:62). The
-          # plugin's `require_magic_comment:` config knob maps
-          # directly onto it.
+          # `opt_in: true` is rbs-inline's "require the magic comment" mode (per upstream parser.rb:62).
+          # The plugin's `require_magic_comment:` config knob maps directly onto it.
           parsed = ::RBS::Inline::Parser.parse(result, opt_in: @require_magic_comment)
           return nil if parsed.nil?
 
@@ -80,11 +66,9 @@ module Rigor
 
           rendered
         rescue ::StandardError => e
-          # WD6 fail-soft — surface a structured error tuple so
-          # the engine's `Environment.for_project` can emit a
-          # `source-rbs-synthesis-failed` info diagnostic
-          # naming the file + the upstream error message,
-          # without crashing analysis.
+          # WD6 fail-soft — surface a structured error tuple so the engine's `Environment.for_project` can
+          # emit a `source-rbs-synthesis-failed` info diagnostic naming the file + the upstream error
+          # message, without crashing analysis.
           [:error, "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}"]
         end
       end
@@ -98,24 +82,19 @@ module Rigor
         source_rbs_synthesizer: nil # set per-instance below
       )
 
-      # Per-instance synthesizer — built from the manifest's
-      # default + the project's plugin config. The manifest
-      # `source_rbs_synthesizer:` is nil at the class level so
-      # the registry sees the instance's override (returned by
-      # `#manifest`, which `Plugin::Registry#source_rbs_synthesizers`
-      # consults via `plugin.manifest.source_rbs_synthesizer`).
+      # Per-instance synthesizer — built from the manifest's default + the project's plugin config. The
+      # manifest `source_rbs_synthesizer:` is nil at the class level so the registry sees the instance's
+      # override (returned by `#manifest`, which `Plugin::Registry#source_rbs_synthesizers` consults via
+      # `plugin.manifest.source_rbs_synthesizer`).
       #
-      # ADR-32 WD10 — `require_magic_comment` defaults to
-      # `true`. Setting it to `false` in `.rigor.yml` flips the
-      # synthesizer into "process every file" mode.
+      # ADR-32 WD10 — `require_magic_comment` defaults to `true`. Setting it to `false` in `.rigor.yml`
+      # flips the synthesizer into "process every file" mode.
       def initialize(services:, config: {})
         super
         @require_magic_comment = config.fetch("require_magic_comment", true) ? true : false
         @synthesizer = Synthesizer.new(require_magic_comment: @require_magic_comment)
-        # Build the per-instance manifest eagerly (before
-        # `freeze`) so the registry's repeated reads return
-        # the same object and we don't need to mutate a
-        # frozen instance later.
+        # Build the per-instance manifest eagerly (before `freeze`) so the registry's repeated reads
+        # return the same object and we don't need to mutate a frozen instance later.
         base = self.class.manifest
         @manifest_with_synth = build_manifest_with_synthesizer(base)
         freeze
@@ -123,10 +102,9 @@ module Rigor
 
       attr_reader :synthesizer
 
-      # Override the manifest-level `source_rbs_synthesizer:`
-      # (which is nil at the class level) with the per-instance
-      # synthesizer built from the merged config. The registry
-      # reads this through `plugin.manifest.source_rbs_synthesizer`.
+      # Override the manifest-level `source_rbs_synthesizer:` (which is nil at the class level) with the
+      # per-instance synthesizer built from the merged config. The registry reads this through
+      # `plugin.manifest.source_rbs_synthesizer`.
       def manifest
         @manifest_with_synth
       end

data/plugins/rigor-rbs-inline/lib/rigor-rbs-inline.rb

@@ -1,17 +1,12 @@
 # frozen_string_literal: true
 
-# rigor-rbs-inline — ingests rbs-inline-shaped comments
-# (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`, attribute
-# `#:`, ivars, generics, override, …) as RBS contributions to
-# the analysis environment.
+# rigor-rbs-inline — ingests rbs-inline-shaped comments (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`,
+# attribute `#:`, ivars, generics, override, …) as RBS contributions to the analysis environment.
 #
-# Per ADR-32 the plugin gates per file on the upstream
-# `# rbs_inline: enabled` magic comment by default. A host
-# context that owns the entire analysis scope (e.g. the
-# ADR-29 browser playground) can set `require_magic_comment:
-# false` in the plugin config to skip the gate — every file
-# the synthesizer sees is treated as if it carried the magic
-# comment.
+# Per ADR-32 the plugin gates per file on the upstream `# rbs_inline: enabled` magic comment by default. A
+# host context that owns the entire analysis scope (e.g. the ADR-29 browser playground) can set
+# `require_magic_comment: false` in the plugin config to skip the gate — every file the synthesizer sees is
+# treated as if it carried the magic comment.
 #
 #     # .rigor.yml
 #     plugins:
@@ -19,6 +14,6 @@
 #         config:
 #           require_magic_comment: false   # default true
 #
-# The plugin depends on the upstream `rbs-inline` gem; Rigor's
-# core `rigortype` gemspec stays zero-dep per ADR-0 / ADR-32 WD1.
+# The plugin depends on the upstream `rbs-inline` gem; Rigor's core `rigortype` gemspec stays zero-dep per
+# ADR-0 / ADR-32 WD1.
 require_relative "rigor/plugin/rbs_inline"

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/analyzer.rb

@@ -9,16 +9,12 @@ module Rigor
     class Rspec < Rigor::Plugin::Base
       # Per-file walker that:
       #
-      # 1. Collects every RSpec scope (each `RSpec.describe`
-      #    plus its nested `describe` / `context` blocks)
+      # 1. Collects every RSpec scope (each `RSpec.describe` plus its nested `describe` / `context` blocks)
       #    via {ScopeWalker}.
-      # 2. Reports duplicate `let(:name)` / `subject(:name)`
-      #    declarations within the same scope (the second
-      #    declaration wins at runtime — an easy
-      #    copy-paste bug).
-      # 3. Reports recursive self-references —
-      #    `let(:user) { user.something }` will infinite-loop
-      #    at runtime — an easy oversight.
+      # 2. Reports duplicate `let(:name)` / `subject(:name)` declarations within the same scope (the second
+      #    declaration wins at runtime — an easy copy-paste bug).
+      # 3. Reports recursive self-references — `let(:user) { user.something }` will infinite-loop at
+      #    runtime — an easy oversight.
       module Analyzer
         Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
 
@@ -49,11 +45,9 @@ module Rigor
         end
 
         def duplicate_diagnostics_for(path, name, decls)
-          # Report each subsequent occurrence; the first
-          # one is the "winner" only by literal source
-          # order, but RSpec lets the LAST declaration win
-          # at runtime, so flag everything after the first
-          # so the user can see the full list.
+          # Report each subsequent occurrence; the first one is the "winner" only by literal source order,
+          # but RSpec lets the LAST declaration win at runtime, so flag everything after the first so the
+          # user can see the full list.
           decls.drop(1).map do |decl|
             Diagnostic.new(
               path: path,
@@ -76,8 +70,7 @@ module Rigor
           end
         end
 
-        # Walks the declaration's block body looking for a
-        # call to its own name with no explicit receiver.
+        # Walks the declaration's block body looking for a call to its own name with no explicit receiver.
         # Returns true if at least one such call exists.
         def self_references?(decl)
           body = decl.block_node&.body

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/let_scope_index.rb

@@ -8,22 +8,17 @@ require_relative "scope_walker"
 module Rigor
   module Plugin
     class Rspec < Rigor::Plugin::Base
-      # Per-file index of RSpec scope hierarchy. Each
-      # describe scope carries:
+      # Per-file index of RSpec scope hierarchy. Each describe scope carries:
       #
-      # - `outer_range`: `Range[Integer]` of line numbers
-      #   covered by the describe's block body (start_line..end_line).
-      # - `describe_const`: the model constant string named in
-      #   `RSpec.describe SomeModel do` / `describe SomeModel do`,
-      #   or `nil` when the describe's first arg is a String
-      #   (`describe ".foo"`).
-      # - `lets`: `Hash{Symbol => Prism::BlockNode}` of `let(:name)
-      #   { ... }` and `subject(:name) { ... }` declarations.
-      #   `:subject` is the key for the implicit `subject { ... }`.
+      # - `outer_range`: `Range[Integer]` of line numbers covered by the describe's block body
+      #   (start_line..end_line).
+      # - `describe_const`: the model constant string named in `RSpec.describe SomeModel do` / `describe
+      #   SomeModel do`, or `nil` when the describe's first arg is a String (`describe ".foo"`).
+      # - `lets`: `Hash{Symbol => Prism::BlockNode}` of `let(:name) { ... }` and `subject(:name) { ... }`
+      #   declarations. `:subject` is the key for the implicit `subject { ... }`.
       #
-      # Used by the plugin's let-binding `dynamic_return`
-      # rule to bind `let`-named method-shape calls inside
-      # `it` bodies to the let block's inferred type.
+      # Used by the plugin's let-binding `dynamic_return` rule to bind `let`-named method-shape calls
+      # inside `it` bodies to the let block's inferred type.
       class LetScopeIndex
         Record = Struct.new(:outer_range, :describe_const, :lets, keyword_init: true) do
           def contains?(line) = outer_range.cover?(line)
@@ -38,27 +33,22 @@ module Rigor
           freeze
         end
 
-        # Returns every record whose outer_range contains the
-        # given line, ordered from outermost to innermost. The
-        # innermost wins on `let` name collisions per Ruby's
-        # method-resolution order (RSpec nested `let` shadows
-        # the outer `let`).
+        # Returns every record whose outer_range contains the given line, ordered from outermost to
+        # innermost. The innermost wins on `let` name collisions per Ruby's method-resolution order (RSpec
+        # nested `let` shadows the outer `let`).
         def records_at(line)
           @records.select { |rec| rec.contains?(line) }
         end
 
-        # ADR-52 slice 5a — every `let` / `subject` name declared
-        # anywhere in the file, across all describe scopes. Feeds the
-        # plugin's `dynamic_return file_methods:` gate: the engine only
-        # consults the rule for a call whose name appears here; the
-        # precise line-scoped resolution stays in `let_block_at`.
+        # ADR-52 slice 5a — every `let` / `subject` name declared anywhere in the file, across all describe
+        # scopes. Feeds the plugin's `dynamic_return file_methods:` gate: the engine only consults the rule
+        # for a call whose name appears here; the precise line-scoped resolution stays in `let_block_at`.
         # @return [Array<Symbol>]
         def let_names
           @records.flat_map { |rec| rec.lets.keys }.uniq
         end
 
-        # Resolves a `let` name at the given line by walking
-        # records innermost to outermost.
+        # Resolves a `let` name at the given line by walking records innermost to outermost.
         # @return [Prism::BlockNode, nil]
         def let_block_at(line, name)
           name_sym = name.to_sym
@@ -68,9 +58,8 @@ module Rigor
           nil
         end
 
-        # Resolves the `describe`-anchor constant name at the
-        # given line. The innermost describe with a constant
-        # anchor wins; describe-with-String anchors are skipped.
+        # Resolves the `describe`-anchor constant name at the given line. The innermost describe with a
+        # constant anchor wins; describe-with-String anchors are skipped.
         # @return [String, nil]
         def describe_const_at(line)
           records_at(line).reverse.each do |rec|
@@ -92,9 +81,8 @@ module Rigor
           if describe_call?(node)
             record = build_record(node, anchor)
             accumulator << record
-            # `describe_call?` already guarantees a `Prism::CallNode`; the
-            # explicit `is_a?` re-states it so the analyzer narrows `node`
-            # from `Prism::Node` and resolves `#block` (a CallNode method).
+            # `describe_call?` already guarantees a `Prism::CallNode`; the explicit `is_a?` re-states it so
+            # the analyzer narrows `node` from `Prism::Node` and resolves `#block` (a CallNode method).
             if node.is_a?(Prism::CallNode) && node.block&.body
               collect(node.block.body, anchor: record.describe_const || anchor, accumulator: accumulator)
             end
@@ -123,8 +111,7 @@ module Rigor
           return false unless ScopeWalker::SCOPE_METHODS.include?(node.name) || node.name == :describe
           return false unless node.block.is_a?(Prism::BlockNode)
 
-          # `RSpec.describe ...` has receiver = RSpec; bare
-          # `describe ... do` has nil receiver. Accept both.
+          # `RSpec.describe ...` has receiver = RSpec; bare `describe ... do` has nil receiver. Accept both.
           node.receiver.nil? || describe_receiver?(node.receiver)
         end
 
@@ -158,11 +145,9 @@ module Rigor
           end
         end
 
-        # Walks the describe's body shallowly: collects every
-        # top-level `let(:name) { ... }` / `subject(:name) { ... }`
-        # / `subject { ... }` declaration. Does NOT recurse into
-        # nested describe / context blocks — those have their
-        # own record built by `collect` above.
+        # Walks the describe's body shallowly: collects every top-level `let(:name) { ... }` /
+        # `subject(:name) { ... }` / `subject { ... }` declaration. Does NOT recurse into nested describe /
+        # context blocks — those have their own record built by `collect` above.
         def self.collect_lets(body)
           return {} unless body.is_a?(Prism::Node)