rigortype 0.3.8 → 0.4.0

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/locale_loader.rb

@@ -35,7 +35,6 @@ module Rigor
           @load_errors = []
         end
 
-        # @return [LocaleIndex]
         def load
           per_key = {} # dotted_key => { locale => Set<String> }
           per_key_kinds = {} # dotted_key => { locale => :string|:array|:hash }

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n.rb

@@ -46,10 +46,7 @@ module Rigor
     #   skipped — the controller/action scope cannot be statically determined there.
     # - View template lazy keys (`t('.key')` inside ERB / Haml / Slim) are validated for key existence and
     #   per-locale coverage. Interpolation variable validation is skipped for view templates (the hash may
-    #   come from controller instance variables not visible in the template). The view scan is a
-    #   project-wide pass surfaced through the per-file diagnostic hook, so under `--workers` each fork-pool
-    #   worker re-emits the full set (the same once-per-run limitation the `load-error` path carries);
-    #   sequential `rigor check` is unaffected.
+    #   come from controller instance variables not visible in the template).
     # - Pluralization (`t('errors.messages.too_short', count: n)`) is recognised at the call site but the
     #   `count` key is not used to validate the locale's pluralization branches.
     # - YAML aliases / merges are accepted (Psych's standard `aliases: true`) but custom Ruby classes
@@ -57,6 +54,7 @@ module Rigor
     class RailsI18n < Rigor::Plugin::Base
       manifest(
         id: "rails-i18n",
+        target_gems: ["i18n"],
         # Bumped 2026-06-23 — view template lazy-key scanning (`t('.key')` inside ERB / Haml / Slim under
         # `view_search_paths`).
         version: "0.3.0",
@@ -105,29 +103,26 @@ module Rigor
         @view_search_paths = Array(config.fetch("view_search_paths")).map(&:to_s)
         @configured_locales = Array(config.fetch("configured_locales")).map(&:to_s)
         @load_errors = []
-        @load_errors_emitted = false
-        @view_diagnostics_emitted = false
       end
 
-      # File-level only: the once-per-run YAML load errors + the runtime (cache-load) error + the
-      # view-template scan. Per-call `t('key')` validation runs over the engine-owned walk via the
-      # node_rule below (ADR-37). The locale index and view diagnostics are lazily loaded + memoised by
-      # `producer_value`.
+      # Returns no rows of its own: every file-level outcome here is run-scoped. The YAML load errors and the
+      # runtime (cache-load) errors are disclosures (#1051); the view-template scan is a positioned batch
+      # registered through `#emit_once` (#1060) — its rows name view files that are usually not analysed
+      # targets, so no per-file return could own them, and returning them from whichever file an instance
+      # saw first repeated the whole batch once per fork-pool worker. Per-call `t('key')` validation runs
+      # over the engine-owned walk via the node_rule below (ADR-37). The locale index and view diagnostics
+      # are lazily loaded + memoised by `producer_value`, so the repeat registrations are no-ops.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:locale_index)
-        diagnostics = []
-        diagnostics.concat(consume_load_error_diagnostics(path)) unless @load_errors.empty?
-        diagnostics << runtime_error_diagnostic(path) if index.nil? && producer_error(:locale_index)
-        unless @view_diagnostics_emitted
-          view_diags = producer_value(:view_diagnostics) || []
-          if (view_err = producer_error(:view_diagnostics))
-            diagnostics << view_runtime_error_diagnostic(path, view_err)
-          else
-            diagnostics.concat(view_diags)
-          end
-          @view_diagnostics_emitted = true
+        disclose_load_errors unless @load_errors.empty?
+        disclose_locale_runtime_error if index.nil? && producer_error(:locale_index)
+        view_diags = producer_value(:view_diagnostics) || []
+        if (view_err = producer_error(:view_diagnostics))
+          disclose_view_runtime_error(view_err)
+        else
+          emit_once(:view_diagnostics, view_diags)
         end
-        diagnostics
+        []
       end
 
       # The lazy-key (`t('.key')`) expansion needs the enclosing method (the controller action), supplied
@@ -210,35 +205,39 @@ module Rigor
       end
 
       # The runner only invokes `diagnostics_for_file` for Ruby files (`paths:` is filtered to `.rb`). YAML
-      # parse errors therefore can't be anchored on the offending locale file directly; instead, we emit
-      # them once per run on the first analyzed Ruby file, naming the offending YAML path in the message.
-      def consume_load_error_diagnostics(path)
-        return [] if @load_errors_emitted
-
-        @load_errors_emitted = true
-        @load_errors.map do |err|
-          Rigor::Analysis::Diagnostic.new(
-            path: path, line: 1, column: 1,
+      # parse errors therefore can't be anchored on the offending locale file directly, and the row used to
+      # be pinned to the first analysed Ruby file — once per plugin INSTANCE, so once per fork-pool worker
+      # (#1051). They go through the run-scoped channel instead: keyed by the locale path that failed, so a
+      # project with two broken YAML files still discloses both, each exactly once, at `.rigor.yml:1:1`.
+      def disclose_load_errors
+        @load_errors.each do |err|
+          disclose_once(
+            "locale-parse:#{err.path}",
             message: "rigor-rails-i18n: failed to parse `#{err.path}`: #{err.message}",
             severity: :warning,
             rule: "load-error"
           )
         end
+        nil
       end
 
-      def runtime_error_diagnostic(path)
+      # #1051 — both of these say the plugin could not READ something the project configured, which is a
+      # run-level fact with no source position; they were repeated on every analysed file (the locale one)
+      # or on each instance's first (the view one). A key distinct from the `:view_diagnostics` batch's:
+      # the two channels share one registration table per plugin.
+      def disclose_locale_runtime_error
         error = producer_error(:locale_index)
-        Rigor::Analysis::Diagnostic.new(
-          path: path, line: 1, column: 1,
+        disclose_once(
+          :locale_index_failed,
           message: "rigor-rails-i18n: failed to load locales: #{error.class}: #{error.message}",
           severity: :warning,
           rule: "load-error"
         )
       end
 
-      def view_runtime_error_diagnostic(path, error)
-        Rigor::Analysis::Diagnostic.new(
-          path: path, line: 1, column: 1,
+      def disclose_view_runtime_error(error)
+        disclose_once(
+          :view_scan_failed,
           message: "rigor-rails-i18n: failed to scan view templates: #{error.class}: #{error.message}",
           severity: :warning,
           rule: "load-error"

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

@@ -24,8 +24,8 @@ module Rigor
       module Acronyms
         module_function
 
-        # @param contents [String, nil] the source of `config/initializers/inflections.rb`.
-        # @return [Array<String>] declared acronyms in declaration order. Empty for a missing / unparseable
+        # @param contents — the source of `config/initializers/inflections.rb`.
+        # @return declared acronyms in declaration order. Empty for a missing / unparseable
         #   file, or one that declares none — which leaves composition exactly as it was.
         def discover(contents)
           return [] if contents.nil? || contents.empty?
@@ -51,9 +51,9 @@ module Rigor
         # camelization of the acronym appears at a camel-word boundary — `Oauth` in `OauthMetadata` and in
         # `WellKnown::Oauth`, but never the `Oauth` inside a hypothetical `Xoauth`.
         #
-        # @param name [String] e.g. `"Activitypub::CollectionsController"`.
-        # @param acronyms [Enumerable<String>] as returned by {.discover}.
-        # @return [String] e.g. `"ActivityPub::CollectionsController"`.
+        # @param name — e.g. `"Activitypub::CollectionsController"`.
+        # @param acronyms — as returned by {.discover}.
+        # @return e.g. `"ActivityPub::CollectionsController"`.
         def apply(name, acronyms)
           acronyms.reduce(name) do |current, acronym|
             plain = Rigor::Plugin::Inflector.camelize(acronym.to_s.downcase)

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

@@ -61,20 +61,10 @@ module Rigor
           %r{(?:\A|/)config/}
         ].freeze
 
-        # @param path [String] file being analysed
-        # @param root [Prism::Node]
-        # @param helper_table [HelperTable]
-        # @return [Array<Diagnostic>]
         # The route-helper violations for a single call node (0..2), or `[]` when the node is not an
         # implicit `*_path` / `*_url` helper call, is shadowed by a same-file binding, or is in a
         # suppressed directory. ADR-37: the engine owns the walk; the same-file `shadowing` set is built
         # once as the node-rule file context.
-        #
-        # @param call_node [Prism::Node]
-        # @param helper_table [HelperTable]
-        # @param shadowing [Set<String>]
-        # @param path [String]
-        # @return [Array<Violation>]
         def violations_for(call_node:, helper_table:, shadowing:, path:)
           return [] unless call_node.is_a?(Prism::CallNode) && implicit_helper_call?(call_node)
 

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

@@ -58,6 +58,7 @@ module Rigor
             [nil, "registration", :get, :show]
           ]
         }.freeze
+        Ractor.make_shareable(CONTROLLER_HELPERS)
 
         # 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
@@ -70,11 +71,11 @@ module Rigor
 
         module_function
 
-        # @param resource [String, Symbol] the `devise_for` argument — typically `:users`. Used as both the
+        # @param resource — 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:
+        # @param skip — controllers the project disables via `devise_for :users, skip:
         #   [:registrations]`.
-        # @return [Array<HelperTable::Entry>] one entry per generated `_path` helper. The caller is
+        # @return 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)
@@ -135,6 +136,7 @@ module Rigor
           unlocks: %w[new_unlock_path unlock_path],
           registrations: %w[cancel_registration_path new_registration_path edit_registration_path registration_path]
         }.freeze
+        Ractor.make_shareable(SCOPED_HELPERS)
         private_constant :SCOPED_HELPERS
 
         def scoped_helpers(skip_set)

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

@@ -63,11 +63,12 @@ module Rigor
             ["oauth_authorized_application_url",  1, "/oauth/authorized_applications/:id", :delete, :destroy]
           ]
         }.freeze
+        Ractor.make_shareable(CONTROLLER_HELPERS)
 
         module_function
 
-        # @param skip [Array<Symbol>] controller names the project omits via `skip_controllers :name, ...`.
-        # @return [Array<HelperTable::Entry>] flattened entries.
+        # @param skip — controller names the project omits via `skip_controllers :name, ...`.
+        # @return flattened entries.
         def generate(skip: [])
           skip_set = skip.to_set(&:to_sym)
           CONTROLLER_HELPERS.flat_map do |controller, rows|

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

@@ -43,9 +43,9 @@ module Rigor
 
         module_function
 
-        # @param contents_per_path [Hash{String => String}] file path → source text, read by the caller
+        # @param contents_per_path — 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
+        # @return 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 = {}

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

@@ -43,10 +43,10 @@ module Rigor
 
         module_function
 
-        # @param contents_per_path [Hash{String => String}] file path → source text. The caller is
+        # @param contents_per_path — 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.
+        # @return 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|

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

@@ -26,21 +26,21 @@ module Rigor
 
         attr_reader :entries, :custom_helpers, :devise_resources
 
-        # @param entries [Array<Entry>] freshly built; the factory below is the canonical construction path.
-        # @param custom_helpers [Enumerable<String>] names of project-defined helper methods (typically
+        # @param entries — freshly built; the factory below is the canonical construction path.
+        # @param custom_helpers — 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`
+        # @param devise_resources — 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.
-        # @param grape_prefixes [Enumerable<String>] helper-name prefixes generated by `grape-path-helpers`
+        # @param grape_prefixes — 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.
-        # @param controllers [Enumerable<String>] fully-qualified controller class names the routes file
+        # @param controllers — fully-qualified controller class names the routes file
         #   dispatches to (`"Admin::UsersController"`). Published as the plugin's `:reachability_roots` fact
         #   (ADR-102 WD3) — a controller is an entry point nothing in the project references, so without this
         #   every routed controller reads as unused. Deliberately NOT consulted by any helper-name check.
@@ -58,20 +58,19 @@ module Rigor
           freeze
         end
 
-        # @return [Array<String>] the routed controller class names (see the `controllers:` parameter). Reads
+        # @return the routed controller class names (see the `controllers:` parameter). Reads
         #   through a nil guard rather than `attr_reader` so a table deserialised from a cache slot written
         #   before this field existed answers `[]` instead of `nil`.
         def controllers
           @controllers || []
         end
 
-        # @return [Entry, nil] First matching entry; for the uncountable-noun case this is the index helper
+        # @return First matching entry; for the uncountable-noun case this is the index helper
         #   (the show helper is also registered but starts second).
         def find(helper_name)
           @by_name[helper_name.to_s]&.first
         end
 
-        # @return [Boolean]
         def known?(helper_name)
           @by_name.key?(helper_name.to_s)
         end
@@ -118,7 +117,7 @@ module Rigor
           end
         end
 
-        # @return [Boolean] true when any entry under this helper name accepts the given positional arity.
+        # @return 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)`
@@ -127,7 +126,7 @@ module Rigor
           (@by_name[helper_name.to_s] || []).any? { |entry| entry.arity == arity || entry.arity + 1 == arity }
         end
 
-        # @return [Array<Integer>] all accepted positional arities for a helper name. Empty when unknown.
+        # @return all accepted positional arities for a helper name. Empty when unknown.
         def acceptable_arities(helper_name)
           (@by_name[helper_name.to_s] || []).map(&:arity).uniq
         end

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

@@ -54,11 +54,10 @@ module Rigor
 
         module_function
 
-        # @param contents [String] raw `config/routes.rb` source
-        # @param file_reader [Proc, nil] called with `"name.rb"` to load a
+        # @param contents — raw `config/routes.rb` source
+        # @param file_reader — called with `"name.rb"` to load a
         #   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: [], grape_prefixes: [], acronyms: [])
           parse_result = Prism.parse(contents)
           unless parse_result.errors.empty?

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

@@ -52,6 +52,7 @@ module Rigor
     class RailsRoutes < Rigor::Plugin::Base
       manifest(
         id: "rails-routes",
+        target_gems: %w[actionpack railties],
         # 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
@@ -191,18 +192,12 @@ module Rigor
         publish_reachability_roots(services, table)
       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 run-scoped load-error disclosure (#1051). 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
-          return [] if @load_error_emitted
-
-          @load_error_emitted = true
-          return [load_error_diagnostic(path)]
-        end
-
+        disclose_load_error if table.nil? && @load_error
         []
       end
 
@@ -264,13 +259,11 @@ module Rigor
         nil
       end
 
-      def load_error_diagnostic(path)
-        Rigor::Analysis::Diagnostic.new(
-          path: path, line: 1, column: 1,
-          message: @load_error,
-          severity: :warning,
-          rule: "load-error"
-        )
+      # #1051 — "the routes file did not load" is a fact about the project, not about the file that
+      # happened to be analysed first by this instance, so it goes through the run-scoped channel and the
+      # engine positions it at `.rigor.yml:1:1`, once per run rather than once per fork-pool worker.
+      def disclose_load_error
+        disclose_once(:routes_load_failed, message: @load_error, severity: :warning, rule: "load-error")
       end
     end
 

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

@@ -52,6 +52,7 @@ module Rigor
     class Railties < Rigor::Plugin::Base
       manifest(
         id: "railties",
+        target_gems: ["railties"],
         # Bumped 2026-09-01 (#534 item 2) — the four `Rails.` singleton readers now return lenient
         # nominals instead of `Dynamic[top]`.
         version: "0.2.0",

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

@@ -8,8 +8,18 @@ module Rigor
     class RbNaCl < Base
       manifest(
         id: "rbnacl",
+        target_gems: ["rbnacl"],
         version: "0.1.0",
-        description: "Rigor type support for RbNaCl libsodium bindings"
+        description: "Rigor type support for RbNaCl libsodium bindings",
+        signature_paths: ["sig"],
+        # ADR-26 — `sig/rbnacl.rbs` declares three methods of a class that has many more (`nonce_bytes`,
+        # `key_bytes`, …). Contributing it without opening the receivers would close those classes and
+        # manufacture `call.undefined-method` on correct code, which is the trade the project refuses.
+        open_receivers: [
+          "RbNaCl::SecretBox",
+          "RbNaCl::Signatures::Ed25519::SigningKey",
+          "RbNaCl::Signatures::Ed25519::VerifyKey"
+        ]
       )
 
       # Issue 2 & 5: use robust positional binding extractor and preserve module context
@@ -28,3 +38,5 @@ module Rigor
     end
   end
 end
+
+Rigor::Plugin.register(Rigor::Plugin::RbNaCl)

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Rigor
+  module Plugin
+    class RbsInline < Base
+      # Issue #998 — the two same-line `%a{}` spellings rbs's built-in `RBS::InlineParser` and Steep's inline
+      # mode accept, repaired into the shape the `rbs-inline` gem's writer honours:
+      #
+      # - `# @rbs %a{…} () -> String` — the gem's `@rbs %a{}` rule lexes the annotations and stops, so the
+      #   method type after them is discarded and the method renders `() -> untyped`;
+      # - `#: %a{…} () -> String` — the gem hands the whole payload to `RBS::Parser.parse_method_type`, which
+      #   has no annotation prefix, so the line becomes a `SyntaxErrorAssertion` and nothing of it survives.
+      #
+      # Both were silent (ADR-32 WD12), and the second reached users as #997's "did not parse … DROPPED"
+      # notice on input that is valid RBS for the other two readers.
+      #
+      # This is a post-parse repair of the gem's annotation list, not a rewrite of the Ruby source. A source
+      # rewrite would have to put the annotation and the method type on two comment lines — the gem has no
+      # one-line spelling for the pair, which is the defect — and inserting a line moves every later line,
+      # including the ones a `#:` notice reports and the one a `def` uses to find its comment block.
+      #
+      # The repair is exact rather than heuristic because every step is the gem's own reading:
+      #
+      # - the leading `%a{…}` spellings are delimited by the gem's own `Tokenizer`, the lexer that already
+      #   accepts them in the own-line form, so what counts as an annotation cannot drift from upstream;
+      # - each half is re-read by the gem's own `AnnotationParser` as the comment the author would have written
+      #   in the own-line form (`# @rbs %a{…}`, then `# @rbs () -> String` or `#: () -> String`), on the same
+      #   line and column, so the replacement annotations are indistinguishable from ones upstream built;
+      # - the split lands only when the remainder re-reads as a well-formed method type. Anything else keeps
+      #   the gem's original annotation untouched, so a genuinely malformed line still reaches the WD12
+      #   notices, and a split can never trade one silent loss for another.
+      module SameLineAnnotations
+        module_function
+
+        # The `@rbs` marker as the gem's `annotation_comment?` detects it, with the whitespace before it.
+        RBS_MARKER = /\A\s*@rbs\b/
+
+        # Replaces, in `parsing_result.annotations`, every same-line form that splits cleanly with the
+        # annotation and the method type it spells. Idempotent: a repaired list has no same-line form left.
+        def split!(parsing_result)
+          return parsing_result unless parsing_result.is_a?(::RBS::Inline::AnnotationParser::ParsingResult)
+
+          parsing_result.annotations.replace(parsing_result.annotations.flat_map { |annotation| expand(annotation) })
+          parsing_result
+        end
+
+        # Every `ParsingResult` a parsed declaration tree holds, which are the objects the writer reads.
+        def each_parsing_result(nodes, &)
+          nodes.each do |node|
+            comments = node.respond_to?(:comments) ? node.comments : nil
+            yield comments if comments.is_a?(::RBS::Inline::AnnotationParser::ParsingResult)
+            each_parsing_result(node.members, &) if node.respond_to?(:members)
+          end
+        end
+
+        # The text an `@rbs %a{…}` line carries after its annotations that the gem discarded — `nil` when
+        # there is none. Call it on an annotation {.split!} has already seen: a remainder that survives the
+        # split is one that did not read as a method type.
+        def dropped_remainder(annotation)
+          return nil unless annotation.is_a?(::RBS::Inline::AST::Annotations::RBSAnnotation)
+
+          parts = same_line_parts(annotation)
+          parts && parts[2].strip
+        end
+
+        def expand(annotation)
+          parts = same_line_parts(annotation)
+          return [annotation] if parts.nil?
+
+          prefix, spellings, rest = parts
+          method_type = reparse(annotation, "##{prefix}#{rest}")
+          return [annotation] unless well_formed_method_type?(method_type)
+
+          # Re-read even when `annotation` already is the `@rbs %a{}` carrier: the original still spans the
+          # method type in its source, and {.dropped_remainder} reads exactly that to report a failed split.
+          carrier = reparse(annotation, "# @rbs #{spellings.join(' ')}")
+          return [annotation] unless carrier.is_a?(::RBS::Inline::AST::Annotations::RBSAnnotation)
+
+          [carrier, method_type]
+        end
+
+        # `[prefix, spellings, rest]` for an annotation whose payload opens with one or more `%a{…}` and
+        # continues with something else, or `nil`. `prefix` is the marker as written (`" @rbs"` or `":"`),
+        # so the re-read keeps the gem's continuation offset for a multi-line comment block.
+        def same_line_parts(annotation)
+          # `annotations` also holds the `CommentLines` of plain prose, which has no `source` to read.
+          prefix =
+            case annotation
+            when ::RBS::Inline::AST::Annotations::RBSAnnotation
+              annotation.source.string[RBS_MARKER]
+            when ::RBS::Inline::AST::Annotations::SyntaxErrorAssertion
+              ":" if annotation.source.string.start_with?(":")
+            end
+          return nil if prefix.nil?
+
+          spellings, rest = leading_annotations(annotation.source.string.delete_prefix(prefix))
+          return nil if spellings.empty? || rest.strip.empty?
+
+          [prefix, spellings, rest]
+        end
+
+        # The `%a{…}` tokens the gem's tokenizer reads at the head of `body`, and the unread text after them.
+        def leading_annotations(body)
+          tokenizer = ::RBS::Inline::AnnotationParser::Tokenizer.new(StringScanner.new(body))
+          trivia = ::RBS::Inline::AST::Tree.new(:rigor_same_line_annotations)
+          tokenizer.advance(trivia)
+          tokenizer.advance(trivia)
+
+          spellings = []
+          while tokenizer.type?(::RBS::Inline::AnnotationParser::Tokens::T_ANNOTATION)
+            spellings << tokenizer.lookahead1[1]
+            tokenizer.advance(trivia)
+          end
+          [spellings, tokenizer.rest]
+        end
+
+        # Reads `comment_text` through the gem's `AnnotationParser` as if it stood where `annotation`'s comment
+        # block does — same first line, same column, continuation lines re-prefixed with the `#` that
+        # `CommentLines#string` strips — and returns the one annotation it yields, or `nil`.
+        def reparse(annotation, comment_text)
+          location = annotation.source.comments.first&.location
+          return nil if location.nil?
+
+          indent = " " * location.start_column
+          padding = "\n" * (location.start_line - 1)
+          source = "#{padding}#{indent}#{comment_text.gsub("\n") { "\n#{indent}#" }}\n"
+          results = ::RBS::Inline::AnnotationParser.parse(::Prism.parse(source).comments)
+          return nil unless results.size == 1
+
+          annotations = results.first.annotations
+          annotations.size == 1 && annotations.first.is_a?(::RBS::Inline::AST::Annotations::Base) ? annotations.first : nil
+        end
+
+        def well_formed_method_type?(annotation)
+          case annotation
+          when ::RBS::Inline::AST::Annotations::MethodTypeAssertion
+            true
+          when ::RBS::Inline::AST::Annotations::Method
+            annotation.method_types.is_a?(Array) && annotation.error_source.nil?
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end