rigortype 0.3.8 → 0.4.0

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "rigor/plugin"
+require_relative "rbs_inline/same_line_annotations"
 
 # ADR-32 — bundled `rigor-rbs-inline` plugin.
 #
@@ -61,9 +62,45 @@ module Rigor
 
         COMMENT_LINE = /\A\s*#/
 
-        private_constant :ECHOED_ANNOTATION, :DECLARATION_LINE, :COMMENT_LINE
+        # The RBS annotation the synthesizer writes on every member whose type upstream DEFAULTED rather
+        # than read off an annotation (issue #823). Its meaning is normative in
+        # `docs/type-specification/rbs-extended.md`: the declaration states the member's presence and its
+        # parameters, and says nothing about what it returns, so the engine infers the return from the body
+        # instead of adopting the placeholder. `Rigor::RbsExtended.inferred_return?` is the reader.
+        INFERRED_RETURN_ANNOTATION = "rigor:v1:inferred-return"
 
-        # @param require_magic_comment [Boolean] when `false` (the default since ADR-93 WD1), the magic
+        # The RBS annotation the synthesizer writes on every member where upstream defaulted EVERY type
+        # slot — every parameter and the return alike — because the author's comment block asserted nothing
+        # about this member's own contract (issue #991). This is a strictly narrower condition than
+        # {INFERRED_RETURN_ANNOTATION}: that one fires whenever the return alone defaulted, which is also
+        # true of a member whose parameters WERE annotated (`# @rbs num: Float` with no `# @rbs return:`).
+        # This annotation distinguishes "nobody said anything about this member" from "the return half was
+        # left to inference" — the two collapse under return-only provenance, because no equivalent
+        # per-parameter survivor exists to separate them (see {DEFAULTED_TYPE_NAME}), so this constant
+        # exists precisely to carry that missing half. Its meaning is normative in
+        # `docs/type-specification/rbs-extended.md`. `Rigor::RbsExtended.inferred_signature?` is the reader.
+        INFERRED_SIGNATURE_ANNOTATION = "rigor:v1:inferred-signature"
+
+        # The stand-in type handed to upstream's `Writer#default_type`, and the whole reason this plugin can
+        # tell a defaulted type from an authored one. `RBS::Inline::Writer` substitutes `default_type`
+        # wherever the author wrote nothing — `return_type || default_type` in `RubyDef#method_overloads`,
+        # `attribute_type || default_type` in `RubyAttr#rbs` — and leaves an authored type alone. Rendering
+        # with a distinctive stand-in therefore makes "the author did not write this" a fact in the output
+        # rather than a guess about it: a member whose return renders as this name was defaulted, and one
+        # that renders `untyped` was WRITTEN `untyped` by its author (`#: (String) -> untyped`), which is a
+        # real contract and stays one.
+        #
+        # `default_type` is upstream's own public accessor for exactly this substitution, and `Writer.write`
+        # yields the writer to configure it, so nothing here reaches into upstream internals. The stand-in
+        # never survives into the contributed RBS — {#mark_inferred_returns} rewrites every occurrence back
+        # to `untyped` — which is not cosmetic: an undeclared type alias makes `RBS::DefinitionBuilder` raise
+        # `NoTypeFoundError` for the whole class, the same failure ADR-93 WD4's Finding 5 measured on
+        # `#:nodoc:`.
+        DEFAULTED_TYPE_NAME = :rigor__inline_defaulted
+
+        private_constant :ECHOED_ANNOTATION, :DECLARATION_LINE, :COMMENT_LINE, :DEFAULTED_TYPE_NAME
+
+        # @param require_magic_comment — when `false` (the default since ADR-93 WD1), the magic
         #   comment is not required and the file is processed only if it actually carries an annotation — see
         #   {#annotated?}. When `true` (the old ADR-32 WD2 gate), only files opening with
         #   `# rbs_inline: enabled` are processed, and upstream's opt-in semantics apply verbatim.
@@ -95,7 +132,11 @@ module Rigor
           return nil if parsed.nil?
 
           uses, decls, rbs_decls = parsed
-          rendered = reattach_declaration_annotations(::RBS::Inline::Writer.write(uses, decls, rbs_decls))
+          # Issue #998 — before the writer reads the annotation lists, so a same-line `%a{…} () -> T` renders
+          # with its method type and its annotation both attached. See {SameLineAnnotations}.
+          SameLineAnnotations.each_parsing_result(decls) { |comments| SameLineAnnotations.split!(comments) }
+          rendered = mark_inferred_returns(render_with_defaulted_marker(uses, decls, rbs_decls))
+          rendered = reattach_declaration_annotations(rendered)
           return nil if rendered.nil? || rendered.strip.empty?
 
           notices = unhonoured_annotations(result)
@@ -109,6 +150,147 @@ module Rigor
 
         private
 
+        # Upstream's writer, told to substitute {DEFAULTED_TYPE_NAME} instead of `untyped` wherever the
+        # author wrote no type. See that constant for why the distinction is worth a stand-in.
+        def render_with_defaulted_marker(uses, decls, rbs_decls)
+          marker = ::RBS::Types::Alias.new(
+            name: ::RBS::TypeName.new(namespace: ::RBS::Namespace.empty, name: DEFAULTED_TYPE_NAME),
+            args: [],
+            location: nil
+          )
+          ::RBS::Inline::Writer.write(uses, decls, rbs_decls) { |writer| writer.default_type = marker }
+        end
+
+        # Issue #823 — the sibling rule. ADR-93 WD1 gates synthesis on a file that carries an annotation;
+        # inside such a file upstream emits a full `def f: (untyped x) -> untyped` skeleton for every
+        # unannotated `def`, and Rigor trusts an accepted signature over body inference. So one `# @rbs`
+        # anywhere in a file used to retype every OTHER method in it to `untyped` — the same mechanism
+        # ADR-93 WD1 measured project-wide before the file gate landed (mail 26 → 42 diagnostics), just
+        # scoped to the annotated file. An annotation on one method must not change the typing of its
+        # siblings in either direction.
+        #
+        # The skeleton is kept — that is what PR #779's member-level drop got wrong, because a partially
+        # declared class reads to RBS as a fully declared one (32 `call.undefined-method` and 12
+        # `call.wrong-arity` on `new`, and 44 classes to `Dynamic[top]` behind cross-file references that
+        # stopped resolving). What changes is what the skeleton CLAIMS: a defaulted type slot is rewritten
+        # back to `untyped` and its member is annotated {INFERRED_RETURN_ANNOTATION}, so the declaration
+        # keeps the class's full method surface, `new`'s arity and every cross-file name, and states nothing
+        # about the return. The engine reads the annotation in `RbsDispatch` and falls through to the same
+        # body-inference tier an undeclared method takes.
+        #
+        # A member additionally carries {INFERRED_SIGNATURE_ANNOTATION} when EVERY type slot on it —
+        # not only the return — defaulted: a fully bare `def`, or one whose only annotation lives on a
+        # sibling member the file also happens to carry. A member with a parameter annotated (`# @rbs num:
+        # Float`) but no `# @rbs return:` still gets {INFERRED_RETURN_ANNOTATION} (the return did default),
+        # but NOT this one — the author asserted something about the member, just not its return. Issue
+        # #991's `call.wrong-arity` reads this one rather than the return-only annotation, because the
+        # arity question is about the parameter list, and the parameter list is exactly what tells the two
+        # cases apart.
+        #
+        # Two properties make the rewrite safe rather than clever:
+        #
+        # - the stand-in is a token this plugin injected, so replacing it is exact — it can only appear
+        #   where upstream substituted it (a comment echoing the same word would merely read `untyped`);
+        # - the lines to annotate come from `RBS::Parser` reading the writer's own output, not from a
+        #   pattern over it, and the replacement is length-preserving per line, so the parser's line numbers
+        #   still address the same members after it.
+        #
+        # Marking is best-effort and the rewrite is not: if the probe parse is skipped or fails, the file
+        # still ships with today's `untyped` skeleton rather than an unresolvable alias (see
+        # {DEFAULTED_TYPE_NAME}). That asymmetry is why the encoding guard is shaped the way it is. Invalid
+        # UTF-8 does not reach here today — the RDoc-directive scan above raises on it first, and {#call}'s
+        # rescue routes the file to WD6 — but the guarded parse is the one `RbsLoader.add_virtual_rbs`
+        # documents as HANG-prone on pre-4.1 rbs lexers, and a hang escapes every rescue there is. So the
+        # probe is skipped for a byte sequence it could hang on, while the substitution runs over bytes and
+        # therefore always completes.
+        def mark_inferred_returns(rendered)
+          return rendered if rendered.nil? || !rendered.b.include?(DEFAULTED_TYPE_NAME.to_s)
+
+          return_lines, signature_lines =
+            rendered.valid_encoding? ? defaulted_member_lines(rendered) : [Set.new, Set.new]
+          scrubbed = rendered.b.gsub(DEFAULTED_TYPE_NAME.to_s, "untyped").force_encoding(rendered.encoding)
+          return scrubbed if return_lines.empty?
+
+          scrubbed.lines.each_with_index.flat_map do |line, index|
+            line_number = index + 1
+            next line unless return_lines.include?(line_number)
+
+            indent = line[/\A[ \t]*/]
+            annotations = ["#{indent}%a{#{INFERRED_RETURN_ANNOTATION}}\n"]
+            annotations << "#{indent}%a{#{INFERRED_SIGNATURE_ANNOTATION}}\n" if signature_lines.include?(line_number)
+            [*annotations, line]
+          end.join
+        end
+
+        # The 1-based lines of every member in `rendered` whose return type (or, for an attribute, whose
+        # type) is the defaulted stand-in — and, of those, the subset where EVERY type slot on the member
+        # defaulted, not only the return. A member's `location.start_line` is the line its `def` /
+        # `attr_*` keyword sits on, which is where the annotation has to go. Returns `[return_lines,
+        # signature_lines]`; `signature_lines` is always a subset of `return_lines`, since a member cannot
+        # have every slot defaulted without its return being one of them.
+        def defaulted_member_lines(rendered)
+          buffer = ::RBS::Buffer.new(name: "(rigor: inline defaulted-type probe)", content: rendered)
+          _, _directives, decls = ::RBS::Parser.parse_signature(buffer)
+          collect_defaulted_member_lines(decls, Set.new, Set.new)
+        rescue ::StandardError
+          # The writer's own output failing to parse is a condition the loader already handles (ADR-32 WD6
+          # fail-soft drops the entry). Declining to mark here keeps that the only failure.
+          [Set.new, Set.new]
+        end
+
+        def collect_defaulted_member_lines(nodes, return_lines, signature_lines)
+          nodes.each do |node|
+            next unless node.respond_to?(:members)
+
+            node.members.each do |member|
+              classify_defaulted_member(member, return_lines, signature_lines)
+            end
+            collect_defaulted_member_lines(
+              node.members.grep(::RBS::AST::Declarations::Base), return_lines, signature_lines
+            )
+          end
+          [return_lines, signature_lines]
+        end
+
+        def classify_defaulted_member(member, return_lines, signature_lines)
+          case member
+          when ::RBS::AST::Members::MethodDefinition
+            return unless member.overloads.any? { |o| defaulted_type?(o.method_type.type.return_type) }
+
+            line = member.location&.start_line
+            return if line.nil?
+
+            return_lines << line
+            signature_lines << line if member.overloads.all? { |o| fully_defaulted_overload?(o) }
+          when ::RBS::AST::Members::Attribute
+            return unless defaulted_type?(member.type)
+
+            line = member.location&.start_line
+            return if line.nil?
+
+            # An attribute has exactly one type slot (the value type, shared by its reader and writer
+            # overloads), so "the type defaulted" and "every type slot defaulted" are the same fact.
+            return_lines << line
+            signature_lines << line
+          end
+        end
+
+        # True when every parameter type and the return type of `overload` — everything
+        # `RBS::Types::Function#each_type` yields — is the defaulted stand-in, i.e. the author's comment
+        # block asserted nothing about this overload's own contract. Block-type provenance is
+        # deliberately not part of this: a block parameter's shape does not bear on the positional arity
+        # #991 exists to check, and upstream defaults it independently of the parameter list either way.
+        def fully_defaulted_overload?(overload)
+          function = overload.method_type.type
+          return false unless function.respond_to?(:each_type)
+
+          function.each_type.all? { |type| defaulted_type?(type) }
+        end
+
+        def defaulted_type?(type)
+          type.is_a?(::RBS::Types::Alias) && type.name.name == DEFAULTED_TYPE_NAME
+        end
+
         # Re-attaches a class- or module-level `%a{…}` that upstream's writer dropped (#452).
         #
         # `RBS::Inline::Writer` emits a member's annotations as real annotation lines and a *declaration's*
@@ -175,29 +357,153 @@ module Rigor
         # These are invisible without a report: synthesis succeeds, and the annotation comment is even echoed
         # into the generated RBS, so the omission shows up neither in the output nor at runtime.
         #
-        # The one case today is `module-self`, where the two inline-RBS dialects disagree on spelling. rbs's
-        # own `docs/inline.md` documents `# @rbs module-self: Foo`; the rbs-inline gem's grammar is
-        # `# @rbs module-self Foo`, without the colon. Handed the colon form the gem still builds a
-        # `ModuleSelf` annotation but extracts no types from it, so an empty `self_types` on a parsed
-        # annotation is a precise signature for "the author asked for a constraint we did not apply".
-        # Measured both ways in `docs/notes/20260730-inline-rbs-parser-grammar-diff.md`.
+        # Five cases today:
         #
-        # Deliberately narrow. A construct the gem's parser REJECTS already routes through WD6's error path,
-        # and one it never recognised at all is upstream's grammar to define (WD3) — guessing at those would
-        # make this a lint on comment prose, which is exactly the false-positive cost ADR-5 ranks first.
+        # - `module-self`, where the two inline-RBS dialects disagree on spelling. rbs's own `docs/inline.md`
+        #   documents `# @rbs module-self: Foo`; the rbs-inline gem's grammar is `# @rbs module-self Foo`,
+        #   without the colon. Handed the colon form the gem still builds a `ModuleSelf` annotation but
+        #   extracts no types from it, so an empty `self_types` on a parsed annotation is a precise signature
+        #   for "the author asked for a constraint we did not apply". Measured both ways in
+        #   `docs/notes/20260730-inline-rbs-parser-grammar-diff.md`.
+        # - a `#:` line whose type does not parse (issue #997). Upstream's own tolerant parse
+        #   ({#parse_type_method_type} in its `annotation_parser.rb`) never raises on this: it consumes the
+        #   rest of the line into a `SyntaxErrorAssertion` and moves on, so nothing upstream ever surfaces
+        #   the failure. Measured at 568138c2: `#: (finite-float) -> String` above a `def` synthesized no
+        #   signature for it AT ALL, and `rigor check` on the file reported nothing beyond an unrelated
+        #   `rbs.coverage.missing-gem` info — the annotation was indistinguishable from one never written,
+        #   which ADR-93's "an inline annotation is a live contract" forbids.
+        # - an `# @rbs %a{…}` line whose text after the annotations is not a method type (issue #998). The
+        #   gem's `@rbs %a{}` rule lexes the annotations and ignores the rest of the line, so
+        #   `# @rbs %a{pure} (finite-float) -> String` keeps `%a{pure}` and discards the signature beside it
+        #   without a word. A remainder that IS a method type is not reported, because
+        #   {SameLineAnnotations.split!} has already made it bind — the notice is for what that repair
+        #   could not read.
+        # - an `# @rbs name: T` parameter (or local-variable) annotation whose `T` does not parse (issue
+        #   #1019, row H). The gem's grammar makes the colon-and-type optional — {#parse_var_decl} always
+        #   builds a `VarType`, even when `parse_type` fell through — so a malformed type leaves `name`
+        #   present and `type` `nil` rather than raising: `# @rbs n: Integer[1..10]` names `n` and leaves its
+        #   type unset. `Writer#default_type` then fills the empty slot the same way an UNANNOTATED parameter
+        #   is filled, so `VarType#type.nil?` is indistinguishable downstream from "the author wrote nothing"
+        #   without this check — the same silent-drop shape #997 closed for `#:` lines and `return:`, now
+        #   closed for `name:`.
+        # - an `@rbs`-prefixed comment paragraph whose body is not one of the gem's known annotation shapes
+        #   (issue #1019, row B). {RBS::Inline::AnnotationParser#annotation_comment?} matches a `\b` word
+        #   boundary right after `@rbs`, so `# @rbs-ext …` is inside its net — the gem treats it as an `@rbs`
+        #   annotation attempt — but {RBS::Inline::AnnotationParser#parse_annotation}'s `case` has no branch
+        #   for what follows `-ext`, falls through with no `else`, and returns `nil`. `AnnotationParser#parse`
+        #   then folds the whole paragraph back into a `CommentLines` — the SAME class an ordinary comment
+        #   parses to — so nothing distinguishes "the gem tried to read this as `@rbs` and failed" from
+        #   "this was never meant to be one" except the marker the gem itself keyed on. {SameLineAnnotations::
+        #   RBS_MARKER} already carries that exact marker (documented there as "the `@rbs` marker as the
+        #   gem's `annotation_comment?` detects it"), reused here rather than duplicated, so a `CommentLines`
+        #   paragraph is only reported when the gem's own detector would have called it an `@rbs` attempt.
+        #
+        # The list is repaired by {SameLineAnnotations.split!} first, exactly as the synthesis path repairs
+        # its own, so a valid same-line `#: %a{…} () -> T` is not reported as a `#:` line that failed to
+        # parse: it did not fail, it binds.
+        #
+        # Deliberately narrow otherwise. A construct the gem's parser REJECTS already routes through WD6's
+        # error path, and one it never recognised at all is upstream's grammar to define (WD3) — guessing at
+        # those would make this a lint on comment prose, which is exactly the false-positive cost ADR-5 ranks
+        # first. `SyntaxErrorAssertion` is neither: the gem's OWN parser recognised the `#:` shape and
+        # positively flagged its payload as unparseable, so reporting it is naming a fact rbs-inline already
+        # computed, not guessing at one. The row-B check is the same kind of fact, read off the gem's own
+        # marker rather than a fact rbs-inline names with a dedicated AST class — nothing else in the grammar
+        # collapses a recognised-but-unparseable paragraph into ordinary prose.
         def unhonoured_annotations(prism_result)
           ::RBS::Inline::AnnotationParser.parse(prism_result.comments).flat_map do |parsed|
-            parsed.each_annotation.filter_map do |annotation|
-              next unless annotation.is_a?(::RBS::Inline::AST::Annotations::ModuleSelf)
-              next unless annotation.self_types.empty?
+            repaired = SameLineAnnotations.split!(parsed)
+            unrecognised_tag_notices(repaired) + repaired.each_annotation.filter_map do |annotation|
+              case annotation
+              when ::RBS::Inline::AST::Annotations::ModuleSelf
+                next if annotation.self_types.any?
 
-              "`@rbs module-self` contributed no self-type constraint. Rigor reads the " \
-                "`# @rbs module-self Foo` spelling; `# @rbs module-self: Foo` (the spelling in rbs's own " \
-                "inline documentation) is not honoured here."
+                "`@rbs module-self` contributed no self-type constraint. Rigor reads the " \
+                  "`# @rbs module-self Foo` spelling; `# @rbs module-self: Foo` (the spelling in rbs's own " \
+                  "inline documentation) is not honoured here."
+              when ::RBS::Inline::AST::Annotations::SyntaxErrorAssertion
+                syntax_error_assertion_notice(annotation)
+              when ::RBS::Inline::AST::Annotations::RBSAnnotation
+                dropped_remainder_notice(annotation)
+              when ::RBS::Inline::AST::Annotations::VarType
+                var_type_notice(annotation)
+              end
             end
           end.uniq
         end
 
+        # Issue #997 — the line comes off the annotation's OWN `Prism::Comment` location, not the
+        # synthesized RBS buffer: unlike {Environment::RbsLoader#unresolved_type_name_detail}'s position,
+        # this one is read straight from the `.rb` file this synthesis call is fresh over (the per-file
+        # synthesizer cache is content-keyed, so a changed file simply misses rather than replaying a stale
+        # line), so it is the real line the author wrote, not an approximation.
+        def syntax_error_assertion_notice(annotation)
+          line = annotation.source.comments.first&.location&.start_line
+          position = line ? " on line #{line}" : ""
+          "a `#:` annotation#{position} did not parse as an RBS method type or type " \
+            "(`#{annotation.error_string}`) and was DROPPED — the method types as if the annotation had " \
+            "never been written, not merely as if its type were wrong. Fix the RBS syntax to restore it."
+        end
+
+        # Issue #998 — the line is read off the annotation's own comment, as in {#syntax_error_assertion_notice}.
+        def dropped_remainder_notice(annotation)
+          remainder = SameLineAnnotations.dropped_remainder(annotation)
+          return nil if remainder.nil?
+
+          line = annotation.source.comments.first&.location&.start_line
+          position = line ? " on line #{line}" : ""
+          "the text after the `%a{…}` annotation#{position} (`#{remainder}`) did not parse as an RBS method " \
+            "type and was DROPPED — the annotation is kept, but the method types as if no signature had been " \
+            "written beside it. Fix the RBS syntax to restore it."
+        end
+
+        # Issue #1019, row H — a `# @rbs name: T` whose `T` the gem's `parse_type` could not build, read off
+        # {RBS::Inline::AST::Annotations::VarType#type} being `nil` rather than off any pattern over the
+        # comment text. Silent otherwise: {Writer#default_type} fills the slot exactly as it fills a
+        # parameter nobody annotated, so `(untyped n)` does not distinguish "wrote nothing" from "wrote a
+        # type RBS could not parse". `raw` is `nil` (and the notice withheld) for the colon-less `# @rbs
+        # name` shorthand — the grammar accepts it too, but with no text to name as the dropped type it is a
+        # bare mention, not a failed assertion.
+        def var_type_notice(annotation)
+          return nil if annotation.type
+
+          raw = annotation.source.string[/#{Regexp.escape(annotation.name.to_s)}\s*:\s*(.+)\z/, 1]&.strip
+          return nil if raw.nil? || raw.empty?
+
+          line = annotation.source.comments.first&.location&.start_line
+          position = line ? " on line #{line}" : ""
+          "a `# @rbs #{annotation.name}:` annotation#{position} (`#{raw}`) did not parse as an RBS type " \
+            "and was DROPPED — the parameter types as `untyped`, not merely as if its type were wrong. If " \
+            "`#{raw}` is a Rigor refinement, write it as an `%a{rigor:v1:param: #{annotation.name} is " \
+            "#{raw}}` annotation beside the plain RBS type instead — see " \
+            "docs/manual/16-rbs-extended-annotations.md — to restore type coverage."
+        end
+
+        # Issue #1019, row B — an `@rbs`-prefixed comment paragraph the gem's OWN detector
+        # ({RBS::Inline::AnnotationParser#annotation_comment?}) called an `@rbs` annotation attempt, that
+        # `#parse_annotation`'s `case` had no branch for. `# @rbs-ext return: non-empty-string` is the case
+        # in point: `annotation_comment?`'s `/\A#(\s*)@rbs(\b|!)/` matches the `\b` word boundary between
+        # `s` and `-`, so the gem tries to read it as `@rbs`, fails, and folds it back into a `CommentLines`
+        # — the same class a `# rigor: …` or `# @extrbs …` paragraph parses to, which never claimed to be
+        # `@rbs` and must stay silent (row X / row C). {SameLineAnnotations::RBS_MARKER} already carries the
+        # gem's own marker, so matching it here is reading the SAME fact the gem's detector computed, not
+        # inventing a new one — see {#unhonoured_annotations}'s row-B paragraph for why that is not the
+        # "regexp lint on comment prose" WD12 otherwise declines to run.
+        def unrecognised_tag_notices(parsing_result)
+          parsing_result.annotations.grep(::RBS::Inline::AST::CommentLines).filter_map do |lines|
+            first_line = lines.string.each_line.first.to_s.strip
+            next unless SameLineAnnotations::RBS_MARKER.match?(first_line)
+
+            line = lines.comments.first&.location&.start_line
+            position = line ? " on line #{line}" : ""
+            "a comment#{position} (`##{first_line}`) opens with the `@rbs` marker but its body did not " \
+              "parse as a recognised `@rbs` annotation, so the whole line was DROPPED — this is not a " \
+              "recognised tag, and nothing on it was applied. Use one of the documented `# @rbs` forms " \
+              "(`name: T`, `return: T`, `module-self T`, …), or rename the tag so it does not start with " \
+              "`@rbs`, to avoid this notice."
+          end
+        end
+
         # Rewrite every RDoc directive comment to its spaced spelling (`#:nodoc:` -> `# :nodoc:`) so
         # upstream's annotation grammar never sees it, and re-parse. Two reasons this happens here rather
         # than in {#annotated?}: the directive must not gate a file in, AND it must not reach the synthesis,

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

@@ -20,9 +20,6 @@ module Rigor
 
         module_function
 
-        # @param path [String]
-        # @param root [Prism::Node]
-        # @return [Array<Diagnostic>]
         def diagnose(path:, root:)
           diagnostics = []
           ScopeWalker.collect_scopes(root).each do |outer|

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

@@ -45,13 +45,11 @@ module Rigor
         # 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.
-        # @return [Prism::BlockNode, nil]
         def let_block_at(line, name)
           name_sym = name.to_sym
           records_at(line).reverse.each do |rec|
@@ -62,7 +60,6 @@ module Rigor
 
         # 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|
             return rec.describe_const if rec.describe_const

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

@@ -30,12 +30,8 @@ module Rigor
 
         module_function
 
-        # @param block_node [Prism::BlockNode]
-        # @param describe_const [String, nil]
-        # @param factory_index [Object, nil] something responding to `find(factory_name)` and returning an
+        # @param factory_index — something responding to `find(factory_name)` and returning an
         #   entry that responds to `model_class`.
-        # @param environment [Rigor::Environment, nil]
-        # @return [Rigor::Type, nil]
         def resolve(block_node, describe_const:, factory_index:, environment:)
           tail = body_tail(block_node)
           return nil if tail.nil?

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

@@ -38,13 +38,12 @@ module Rigor
       module MatcherAnalyzer
         module_function
 
-        # @param call_node [Prism::CallNode] the call whose contribution we're computing. Returns nil when
+        # @param call_node — the call whose contribution we're computing. Returns nil when
         #   the call shape does not match `expect(local).to matcher`.
-        # @param environment [Rigor::Environment, nil] the surrounding environment used to resolve a
+        # @param environment — the surrounding environment used to resolve a
         #   matcher's class-name argument to a `Type::Nominal`. When nil, class-name resolution falls back
         #   to a bare `Nominal[<name>]` carrier (sound — the receiver constant may be a user class not in
         #   RBS).
-        # @return [Rigor::FlowContribution, nil]
         def contribution_for(call_node, environment:)
           verb = assertion_verb(call_node)
           return nil if verb.nil?

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

@@ -48,6 +48,7 @@ module Rigor
     class Rspec < Rigor::Plugin::Base
       manifest(
         id: "rspec",
+        target_gems: ["rspec-core"],
         version: "0.3.0",
         description: "Validates RSpec `let` / `subject` declarations within each scope; " \
                      "narrows expect(x).to <matcher> assertions downstream in `it` bodies; " \

data/plugins/rigor-rspec-rails/lib/rigor/plugin/rspec_rails/have_http_status_analyzer.rb

@@ -40,9 +40,6 @@ module Rigor
         # The matcher violation for a single CallNode, or nil when the node is not a
         # `have_http_status(<int|symbol>)` matcher or its argument is statically valid. ADR-37: the engine
         # owns the walk, so this is per-node logic — no traversal here.
-        #
-        # @param call_node [Prism::Node]
-        # @return [Violation, nil]
         def violation_for(call_node)
           return nil unless call_to_matcher?(call_node)
 

data/plugins/rigor-rspec-rails/lib/rigor/plugin/rspec_rails.rb

@@ -39,6 +39,7 @@ module Rigor
     class RspecRails < Rigor::Plugin::Base
       manifest(
         id: "rspec-rails",
+        target_gems: ["rspec-rails"],
         version: "0.1.0",
         description: "Validates rspec-rails behavioral matchers (have_http_status floor)."
       )

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

@@ -8,6 +8,7 @@ module Rigor
     class SassC < Base
       manifest(
         id: "sassc",
+        target_gems: ["sassc"],
         version: "0.1.0",
         description: "Models SassC native bindings, nominal pointer typedefs, and struct unions.",
         signature_paths: ["sig"]

data/plugins/rigor-shoulda-matchers/lib/rigor/plugin/shoulda_matchers/analyzer.rb

@@ -72,23 +72,15 @@ module Rigor
 
         module_function
 
-        # @param path [String]
-        # @param root [Prism::Node]
-        # @param model_index [Hash{String => Hash}, nil] the `:model_index` fact value — the flat
+        # @param model_index — the `:model_index` fact value — the flat
         #   `class_name => { table:, columns:, associations:, ... }` Hash `rigor-activerecord` publishes
         #   (ADR-9's "the value is data, not objects" contract; see `Activerecord#index_to_published_hash`).
         #   When nil the analyzer falls silent.
-        # @return [Array<Diagnostic>]
         # The matcher violations for a single call node (0..1), or `[]` when it is not a shoulda matcher,
         # sits outside any `describe <ModelConst>` block, or the model is unknown. ADR-37: the engine owns
         # the walk; the model anchor comes from the node-rule `NodeContext` ancestors (the innermost
         # enclosing `describe`-with-constant — nested const describes override, `describe ".method"`
         # string blocks inherit), exactly as the former recursive anchor propagation did.
-        #
-        # @param matcher_call [Prism::Node]
-        # @param ancestors [Array<Prism::Node>]
-        # @param model_index [Hash{String => Hash}, nil]
-        # @return [Array<Violation>]
         def violations_for(matcher_call:, ancestors:, model_index:)
           return [] if model_index.nil?
           return [] unless matcher_invocation?(matcher_call)

data/plugins/rigor-shoulda-matchers/lib/rigor/plugin/shoulda_matchers.rb

@@ -47,6 +47,7 @@ module Rigor
     class ShouldaMatchers < Rigor::Plugin::Base
       manifest(
         id: "shoulda-matchers",
+        target_gems: ["shoulda-matchers"],
         version: "0.1.0",
         description: "Validates shoulda-matchers matchers (validate_presence_of / belong_to / " \
                      "have_many / have_db_column / ...) against :model_index from " \

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

@@ -34,10 +34,6 @@ module Rigor
 
         # The worker-call violations for a single call node (0..2), or `[]` when the node is not a
         # `<Worker>.perform_*` entry call on a known worker. ADR-37: the engine owns the walk.
-        #
-        # @param call_node [Prism::Node]
-        # @param worker_index [WorkerIndex]
-        # @return [Array<Violation>]
         def violations_for(call_node:, worker_index:)
           return [] unless call_node.is_a?(Prism::CallNode) && entry_call?(call_node)
 

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/effects.rb

@@ -52,7 +52,7 @@ module Rigor
 
         module_function
 
-        # @param marker_modules [Array<String>] the modules a worker includes — the plugin's own
+        # @param marker_modules — the modules a worker includes — the plugin's own
         #   `worker_marker_modules:` config, so one project setting drives the arity check and these rows.
         def attributions(marker_modules)
           marker_modules.flat_map do |marker|

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/schedule_scan.rb

@@ -41,6 +41,7 @@ module Rigor
         # `schedule.yml` IS the schedule map — and the nested paths are `sidekiq-scheduler`'s, whose entries
         # live under `:scheduler: :schedule:` (with the bare `:schedule:` form kept for pre-3.0 layouts).
         SCHEDULE_BLOCK_KEY_PATHS = [[], %w[scheduler schedule], %w[schedule]].freeze
+        Ractor.make_shareable(SCHEDULE_BLOCK_KEY_PATHS)
 
         # Errno classes that mean "this path is not readable as a schedule" — swallowed so one bad path does
         # not cost the roots the other paths supply.
@@ -51,7 +52,7 @@ module Rigor
           @schedule_paths = schedule_paths
         end
 
-        # @return [Array<String>] the class names named by a `class:` key in a schedule entry, sorted and
+        # @return the class names named by a `class:` key in a schedule entry, sorted and
         #   unique. NOT yet intersected with the discovered workers — the caller does that.
         def worker_names
           names = Set.new

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/worker_discoverer.rb

@@ -33,7 +33,6 @@ module Rigor
           @marker_modules = marker_modules.to_set { |name| strip_root(name.to_s) }
         end
 
-        # @return [WorkerIndex]
         def discover
           candidates = []
           ruby_files_under(@search_paths).each do |path|

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/worker_index.rb

@@ -39,8 +39,6 @@ module Rigor
         # never `"::WelcomeWorker"`; see {WorkerDiscoverer}), while a QUERY may legitimately arrive rooted:
         # `::WelcomeWorker.perform_async(1)` renders its receiver as `"::WelcomeWorker"`. The root marker is
         # dropped here, once, so no caller needs a `find(name) || find("::#{name}")` retry (#621).
-        #
-        # @return [Entry, nil]
         def find(class_name)
           @by_name[strip_leading_namespace(class_name.to_s)]
         end

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

@@ -54,6 +54,7 @@ module Rigor
     class Sidekiq < Rigor::Plugin::Base
       manifest(
         id: "sidekiq",
+        target_gems: ["sidekiq"],
         # Bumped 2026-08-16 — publishes `:reachability_roots` for `rigor unused` (ADR-102 WD3): the workers
         # a schedule file enqueues by name, which no `perform_async` call site writes down.
         # Bumped 2026-09-01 (#534 item 4) — the enqueue methods return the jid `String`.
@@ -136,12 +137,12 @@ module Rigor
         services.fact_store.publish(plugin_id: manifest.id, name: :reachability_roots, value: roots)
       end
 
-      # File-level only: the load-error emission. The per-call arity validation runs over the engine-owned
+      # File-level only: the load-error disclosure. The per-call arity validation runs over the engine-owned
       # walk via the node_rule below (ADR-37). The worker index is lazily loaded + memoised by
       # `producer_value`, shared by both surfaces.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = producer_value(:worker_index)
-        return [load_error_diagnostic(path)] if index.nil? && producer_error(:worker_index)
+        disclose_load_error if index.nil? && producer_error(:worker_index)
 
         []
       end
@@ -205,10 +206,14 @@ module Rigor
 
       private
 
-      def load_error_diagnostic(path)
+      # Issue #1056 — "the worker index did not load" is a fact about the run's INPUTS, not about the file being
+      # analysed, so it is registered rather than returned: see {Plugin::Base#disclose_once} for the
+      # channel, the `(plugin id, key)` de-duplication and why the engine positions it at `.rigor.yml:1:1`.
+      # Returned from the per-file hook it carried no once-guard at all and repeated on every file.
+      def disclose_load_error
         error = producer_error(:worker_index)
-        Rigor::Analysis::Diagnostic.new(
-          path: path, line: 1, column: 1,
+        disclose_once(
+          :worker_index_load_failed,
           message: "rigor-sidekiq: failed to discover workers: #{error.class}: #{error.message}",
           severity: :warning,
           rule: "load-error"

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

@@ -51,6 +51,7 @@ module Rigor
     class Sinatra < Rigor::Plugin::Base
       manifest(
         id: "sinatra",
+        target_gems: ["sinatra"],
         version: "0.1.0",
         description: "Recognises Sinatra's class-level route DSL via ADR-16 Tier A.",
         block_as_methods: [