rigortype 0.4.6 → 0.4.7

data/lib/rigor/sig_gen/generic_header_scan.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+require_relative "../environment/rbs_loader"
+require_relative "../rooted_glob"
+
+module Rigor
+  module SigGen
+    # Issues #2603 and #2605 — the run-wide view of the parameterless headers of generic classes (`class Array`, as
+    # sig-gen spelled it before #2436) that `sig/` holds, read before the writer changes anything.
+    #
+    # rbs rejects a class with `GenericParameterMismatchError` while any one of its declarations opens it bare, so
+    # the repair is decided per class, across every file the project's RBS env loads from `signature_paths:`: either
+    # every bare opening of the class is repaired, or none is. A class is held back ({#left_bare}) when the body of
+    # any of its bare openings names one of the parameters as a relative constant ({.shadowing_names}), because the
+    # inserted parameter would capture that name, or when one of its bare openings lies outside the sig root, which
+    # the writer never rewrites. Every file under the sig root is read, not only those a candidate of the run routes
+    # to, so a bare header whose source file is gone is repaired too (#2603); the other signature paths are read
+    # and never written.
+    #
+    # A file that is not valid UTF-8, or does not parse, is not read: rbs never loads it, and the writer refuses it.
+    class GenericHeaderScan
+      # One bare opening: the file it is in, the class it opens, the parameter names its body spells, and whether
+      # the file is under the sig root (the writer may rewrite it).
+      Opening = Data.define(:target, :class_name, :names, :writable)
+
+      # @param sig_root — the directory the writer writes to; the only files it may rewrite.
+      # @param signature_dirs — the other directories the RBS env loads (`signature_paths:`), read only. A file
+      #   under the sig root is read once, as a writable one.
+      # @param spelling_for — called with a class name, returns the header spelling to insert
+      #   (`"[unchecked out E]"`), or nil for a class that is not generic with plain parameters only.
+      def self.scan(sig_root:, spelling_for:, signature_dirs: [])
+        new(spelling_for).tap do |scan|
+          scan.read_tree(sig_root, writable: true)
+          signature_dirs.each { |dir| scan.read_tree(dir, writable: false) }
+        end
+      end
+
+      # The names in `names` that the declaration's text after its name (superclass, members, nested declarations)
+      # spells as a relative constant (`E`, `E::X`, not `::E` or `Foo::E`). A method type that declares a name as
+      # its own type parameter (`def m: [E] (E) -> E`) binds every `E` inside it, so its text does not count for
+      # that name. The rest is matched as text, so a comment that spells the name counts.
+      def self.shadowing_names(source, decl, names)
+        start = decl.location[:name].end_pos
+        body = source[start...decl.location.end_pos]
+        names.select do |name|
+          masked = mask_binders(body, binder_ranges(decl, name), start)
+          masked.match?(/(?<![\w:])#{Regexp.escape(name)}(?!\w)/)
+        end
+      end
+
+      # The source ranges of the method types under `decl` (nested declarations included) that declare `name` as a
+      # type parameter of their own.
+      def self.binder_ranges(decl, name, ranges = [])
+        (decl.respond_to?(:members) ? decl.members : []).each do |member|
+          if member.is_a?(RBS::AST::Members::MethodDefinition)
+            member.overloads.each do |overload|
+              type = overload.method_type
+              next unless type.location && type.type_params.any? { |param| param.name.to_s == name }
+
+              ranges << (type.location.start_pos...type.location.end_pos)
+            end
+          end
+          binder_ranges(member, name, ranges)
+        end
+        ranges
+      end
+
+      def self.mask_binders(body, ranges, offset)
+        masked = body.dup
+        ranges.each do |range|
+          from = range.begin - offset
+          masked[from, range.size] = " " * range.size if from >= 0 && from + range.size <= masked.size
+        end
+        masked
+      end
+      private_class_method :mask_binders
+
+      # The parameter names `[unchecked out K, unchecked out V]` declares; nil when it does not parse.
+      def self.parameter_names(spelling)
+        _, _, decls = RBS::Parser.parse_signature("class RigorSigGenProbe#{spelling}\nend\n")
+        decls.first&.type_params&.map { |param| param.name.to_s }
+      rescue RBS::ParsingError
+        nil
+      end
+
+      def initialize(spelling_for)
+        @spelling_for = spelling_for
+        @openings = []
+        @seen = Set.new
+      end
+
+      # Every class to repair, with the spelling to insert: each bare opening of it, in every file read, is clear.
+      def repairs
+        @repairs ||= by_class.reject { |_, openings| openings.any? { |o| blocking?(o) } }
+                             .to_h { |name, _| [name, spelling(name)] }
+      end
+
+      # The files that hold a bare opening of a class in {#repairs}, as their `to_s`.
+      def repair_targets
+        @openings.select { |o| repairs.key?(o.class_name) }.map(&:target).uniq
+      end
+
+      # One entry per class held back: `{ class:, targets:, blocking: [...] }`, where `targets` is every file with a
+      # bare opening of it and `blocking` the openings that hold it back, each `{ target:, reason:
+      # "outside_sig_root" }` (a file the writer does not rewrite) or `{ target:, reason: "names_parameter", names: }`.
+      def left_bare
+        by_class.filter_map do |name, openings|
+          blocking = openings.select { |o| blocking?(o) }
+          next if blocking.empty?
+
+          { class: name, targets: openings.map(&:target).uniq, blocking: blocking.map { |o| blocking_entry(o) } }
+        end
+      end
+
+      def read_tree(dir, writable:)
+        return unless dir.directory?
+
+        RootedGlob.glob(dir.to_s, "**/*.rbs").sort.each do |path|
+          key = realpath(path)
+          read_file(Pathname(path), writable) if @seen.add?(key)
+        end
+      end
+
+      private
+
+      def blocking?(opening)
+        !opening.writable || !opening.names.empty?
+      end
+
+      def blocking_entry(opening)
+        return { target: opening.target, reason: "outside_sig_root" } unless opening.writable
+
+        { target: opening.target, reason: "names_parameter", names: opening.names }
+      end
+
+      def realpath(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def by_class
+        @by_class ||= @openings.group_by(&:class_name).sort.to_h
+      end
+
+      def spelling(name)
+        @spellings ||= {}
+        return @spellings[name] if @spellings.key?(name)
+
+        @spellings[name] = @spelling_for.call(name)
+      end
+
+      def read_file(path, writable)
+        source = path.read
+        return unless source.valid_encoding?
+
+        _, _, decls = RBS::Parser.parse_signature(source)
+        collect([path.to_s, writable], source, decls, [])
+      rescue RBS::ParsingError, SystemCallError
+        nil
+      end
+
+      def collect(target, source, decls, prefix)
+        decls.each do |decl|
+          next unless decl.is_a?(RBS::AST::Declarations::Class) || decl.is_a?(RBS::AST::Declarations::Module)
+
+          # RBS resolves `module Foo; class ::Set` to the top-level `Set`, and so does this key (#2654).
+          path = Environment::RbsLoader.declared_class_path(decl, prefix)
+          record(target, source, decl, path.join("::"))
+          collect(target, source, decl.members, path)
+        end
+      end
+
+      def record(target, source, decl, name)
+        return unless decl.type_params.empty? && decl.location&.[](:name)
+
+        spelled = spelling(name)
+        params = spelled && self.class.parameter_names(spelled)
+        return if params.nil?
+
+        file, writable = target
+        @openings << Opening.new(target: file, class_name: name, writable: writable,
+                                 names: self.class.shadowing_names(source, decl, params))
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/inline_declarations.rb

@@ -23,7 +23,7 @@ module Rigor
     class InlineDeclarations
       # One inline-declared method.
       #
-      # - `method_types` — the declared overloads (`RBS::MethodType`, names as written, unresolved).
+      # - `method_types` — the declared overloads, names as written and unresolved.
       # - `annotations` — the annotation strings the author wrote on the member (`deprecated` for
       #   `%a{deprecated}`), without the synthesizer's own `rigor:v1:inferred-*` markers.
       # - `return_inferred` — the author declared the parameters and not the return: rbs-inline defaulted it,
@@ -112,7 +112,7 @@ module Rigor
         decls.each do |decl|
           next unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
 
-          inner = prefix + [decl.name.to_s.delete_prefix("::")]
+          inner = ::Rigor::Environment::RbsLoader.declared_class_path(decl, prefix)
           @generic_classes[inner.join("::")] ||= decl.type_params.map(&:name) unless decl.type_params.empty?
           decl.members.each { |member| block.call(inner.join("::"), member) }
           each_member(decl.members, inner, &block)

data/lib/rigor/sig_gen/layout_index.rb

@@ -126,8 +126,8 @@ module Rigor
         return unless decl.is_a?(RBS::AST::Declarations::Class) ||
                       decl.is_a?(RBS::AST::Declarations::Module)
 
-        local_name = decl.name.to_s.sub(/\A::/, "")
-        full = prefix.empty? ? local_name : "#{prefix.join('::')}::#{local_name}"
+        path = ::Rigor::Environment::RbsLoader.declared_class_path(decl, prefix)
+        full = path.join("::")
         accumulator[full] ||= rbs_path
         decl.members.each do |member|
           # An `overloading?` member (`def f: ... | ...`) adds to a declaration elsewhere; routing a candidate to
@@ -137,7 +137,7 @@ module Rigor
           self.class.member_keys(member).each { |name, kind| @members[[full, name, kind]] ||= rbs_path }
         end
 
-        record_decls(decl.members, prefix + [local_name], rbs_path, accumulator)
+        record_decls(decl.members, path, rbs_path, accumulator)
       end
     end
   end

data/lib/rigor/sig_gen/method_candidate.rb

@@ -15,7 +15,7 @@ module Rigor
     #   ever `skipped` (`sig.skipped.top-level-def`, #1676).
     # - `method_name` — the def's `Symbol` name.
     # - `kind` — `:instance` or `:singleton`.
-    # - `inferred_return` — `Rigor::Type` instance (or `nil` when the inference pass disqualified the def).
+    # - `inferred_return` — the inferred return type (or `nil` when the inference pass disqualified the def).
     # - `declared_return_rbs` — the existing RBS-declared return spelling, or `nil` when no RBS declares the
     #   method.
     # - `declared_rbs` — for an `inline_overwrite`, or a `tighter_return` over the class's own declaration, the
@@ -33,13 +33,14 @@ module Rigor
     class MethodCandidate
       attr_reader :path, :class_name, :method_name, :kind, :classification,
                   :inferred_return, :declared_return_rbs, :rbs, :skip_reason,
-                  :namespace_kinds, :class_shells, :class_superclasses,
+                  :namespace_kinds, :class_shells, :class_superclasses, :class_type_params,
                   :annotations, :effect_reason, :declared_rbs, :declared_annotations
 
       def initialize(path:, class_name:, method_name:, kind:, classification:, # rubocop:disable Metrics/ParameterLists
                      inferred_return: nil, declared_return_rbs: nil, rbs: nil, skip_reason: nil,
                      namespace_kinds: {}, class_shells: [], class_superclasses: {},
-                     annotations: [], effect_reason: nil, declared_rbs: nil, declared_annotations: [])
+                     annotations: [], effect_reason: nil, declared_rbs: nil, declared_annotations: [],
+                     class_type_params: {})
         @path = path
         @class_name = class_name
         @method_name = method_name
@@ -55,6 +56,10 @@ module Rigor
         # superclasses appear; computed ones are absent. The Writer emits `class Bar < Base` for the leaf when
         # present.
         @class_superclasses = class_superclasses.freeze
+        # Issue #2436 — qualified class name => the type-parameter list a loaded declaration gives it, spelled for
+        # a header (`{ "Array" => "[unchecked out E]" }`). A header the writer opens for one of these classes
+        # carries the list; a class absent from the map is written without one.
+        @class_type_params = class_type_params.freeze
         @annotations = annotations.freeze
         @effect_reason = effect_reason
         @declared_rbs = declared_rbs
@@ -85,7 +90,21 @@ module Rigor
           declared_return_rbs: @declared_return_rbs, rbs: @rbs, skip_reason: @skip_reason,
           namespace_kinds: @namespace_kinds, class_shells: @class_shells,
           class_superclasses: @class_superclasses, annotations: annotations, effect_reason: reason,
-          declared_rbs: @declared_rbs, declared_annotations: @declared_annotations
+          declared_rbs: @declared_rbs, declared_annotations: @declared_annotations,
+          class_type_params: @class_type_params
+        )
+      end
+
+      # A copy carrying the run's reopened-class type parameters (#2436).
+      def with_class_type_params(class_type_params)
+        self.class.new(
+          path: @path, class_name: @class_name, method_name: @method_name, kind: @kind,
+          classification: @classification, inferred_return: @inferred_return,
+          declared_return_rbs: @declared_return_rbs, rbs: @rbs, skip_reason: @skip_reason,
+          namespace_kinds: @namespace_kinds, class_shells: @class_shells,
+          class_superclasses: @class_superclasses, annotations: @annotations, effect_reason: @effect_reason,
+          declared_rbs: @declared_rbs, declared_annotations: @declared_annotations,
+          class_type_params: class_type_params
         )
       end
 

data/lib/rigor/sig_gen/observation_collector.rb

@@ -19,9 +19,7 @@ module Rigor
     # Walks the `--observe=PATH...` tree (default: the project's test roots), parses every `.rb` file with `Prism`,
     # scope- indexes it the same way the main generator does, and records the per-call-site argument-type tuples
     # for every `Prism::CallNode` whose receiver types as a `Type::Nominal`. The {Generator} consumes the
-    # resulting map to render `--params=observed` RBS:
-    #
-    # @return => Array<Array<Rigor::Type>>}]
+    # resulting map to render `--params=observed` RBS.
     #
     # ADR-5 clause 2 compliance: the observed union is the MOST PERMISSIVE parameter contract the existing
     # callers prove sufficient — by construction it accepts every type any caller has already passed. The
@@ -29,8 +27,8 @@ module Rigor
     # user opts in.
     #
     # MVP scope:
-    # - Explicit-receiver calls only (`foo.bar(args)`). Implicit-self calls inside class bodies and RSpec-style
-    #   `let` / `subject` bindings ride on slice 5's optional `rigor-rspec` integration.
+    # - Explicit-receiver calls only (`foo.bar(args)`). Implicit-self calls inside class bodies are skipped;
+    #   RSpec `let` / `subject` receivers are resolved from the spec file (ADR-14 slice 5).
     # - Calls whose receiver does not type as a `Type::Nominal` (e.g. `(some_dynamic).bar(...)`) are skipped —
     #   the collector cannot attribute them to a specific class.
     # - A `T | nil` receiver with one `Nominal` / `Singleton` non-nil member counts as that member (#1389).

data/lib/rigor/sig_gen/observed_call.rb

@@ -3,7 +3,7 @@
 module Rigor
   module SigGen
     # Per-call-site argument observation produced by {ObservationCollector}. ADR-14 follow-up: the earlier MVP
-    # shape (`Array[Type]` of positional types only) could not represent keyword arguments — keyword calls like
+    # shape (positional types only) could not represent keyword arguments — keyword calls like
     # `MethodCatalog.new(path: ..., mutating_selectors: ...)` were silently skipped in that shape. The new shape
     # carries positional and keyword arg types in parallel so the per-position / per-keyword unions can each be
     # reconstructed independently.

data/lib/rigor/sig_gen/path_mapper.rb

@@ -74,6 +74,12 @@ module Rigor
         @sig_root_dir ||= @project_root / sig_root_name
       end
 
+      # Every directory the project's RBS env loads signatures from (`signature_paths:`), resolved against the
+      # project root. The writer reads them to decide a repair (#2605) and writes only under {#sig_root_dir}.
+      def signature_dirs
+        Array(@configuration.signature_paths).map { |path| @project_root / path }
+      end
+
       private
 
       def source_relative_to_root(source_path)

data/lib/rigor/sig_gen/renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../cli/json_document"
+
 require_relative "classification"
 require_relative "superclass_spelling"
 require_relative "write_reporter"
@@ -14,8 +16,7 @@ module Rigor
     # - `:print` (default) — RBS skeletons grouped by source file and class declaration, ready for the user to
     #   paste into `sig/<path>.rbs`.
     # - `:diff` — a unified-style diff comparing the existing RBS spelling (if any) against the inferred
-    #   spelling. The MVP renders a minimal "- declared / + inferred" block; full per-file diffing arrives with
-    #   slice 2's `--write` merge.
+    #   spelling, as a minimal "- declared / + inferred" block.
     # - `:json` — machine-readable payload with the same classification table as `:print`, plus every `skipped`
     #   row with its `skip_reason` (#778).
     class Renderer
@@ -95,11 +96,14 @@ module Rigor
       # mode used to hard-code `class`, which turned a module into a class the moment it held an emittable method —
       # output that raises `RBS::DuplicatedDeclarationError` on load if the real `module` is declared anywhere else
       # (#227). Defaulting to `class` when the map has no entry keeps the pre-existing spelling for a leaf class.
+      # A generic class the run reopens carries its declaration's type parameters, as the written header does (#2436).
       def declaration_header(candidate, class_name)
-        return "module #{class_name}" if candidate.namespace_kinds[class_name] == :module
+        params = candidate.class_type_params[class_name]
+        return "module #{class_name}#{params}" if candidate.namespace_kinds[class_name] == :module
 
         superclass = candidate.class_superclasses[class_name]
-        superclass ? "class #{class_name} < #{SuperclassSpelling.absolute(superclass)}" : "class #{class_name}"
+        head = "class #{class_name}#{params}"
+        superclass ? "#{head} < #{SuperclassSpelling.absolute(superclass)}" : head
       end
 
       def render_diff(candidates)
@@ -130,19 +134,21 @@ module Rigor
         payload = { candidates: candidates.map(&:to_h) }
         payload[:observation] = observation if observation
         payload[:diagnostics] = diagnostics.map(&:to_h) if diagnostics.any?
-        @out.puts(JSON.pretty_generate(payload))
+        @out.puts(JSON.pretty_generate(CLI::JsonDocument.stamp(payload)))
       end
 
       public
 
       # The per-source-file outcomes of a `--write` run, and the `--check` verdict, are reported by
       # {WriteReporter}; these delegate so the command keeps one renderer.
-      def render_write(results:, format:, refused: [])
-        WriteReporter.new(out: @out).render_write(results: results, format: format, refused: refused)
+      def render_write(results:, format:, refused: [], left_bare: [])
+        WriteReporter.new(out: @out).render_write(results: results, format: format, refused: refused,
+                                                  left_bare: left_bare)
       end
 
-      def render_check(results:, format:, refused: [])
-        WriteReporter.new(out: @out).render_check(results: results, format: format, refused: refused)
+      def render_check(results:, format:, refused: [], left_bare: [])
+        WriteReporter.new(out: @out).render_check(results: results, format: format, refused: refused,
+                                                  left_bare: left_bare)
       end
 
       def self.refusal_lines(refused)

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -15,8 +15,8 @@ module Rigor
     # reason has no severity, no profile mapping and no suppression, and forcing it into {RuleCatalog::Entry}
     # would mean inventing four fields that do not apply.
     #
-    # Every id in {Classification::SKIP_DIAGNOSTIC_IDS} MUST have an entry here; the gate is
-    # `spec/rigor/sig_gen/skip_reason_catalog_spec.rb`.
+    # Every id in {Classification::SKIP_DIAGNOSTIC_IDS} MUST have an entry here; the gate is the
+    # `sig.skipped.*` example in `spec/rigor/cli_spec.rb`.
     module SkipReasonCatalog
       class Entry < Data.define(:id, :summary, :explanation, :next_step)
         # Hash-shaped form for `rigor explain --format=json`. String keys, and `kind` distinguishes a skip
@@ -110,6 +110,19 @@ module Rigor
           next_step: "Declare the class in `sig/` with the same type parameters as the inline declaration " \
                      "(`class Box[T]` ... `end`) and re-run; sig-gen then writes the members into it."
         ),
+        "sig.skipped.generic-reopening" => Entry.new(
+          id: "sig.skipped.generic-reopening",
+          summary: "The method reopens a generic class whose type parameters sig-gen cannot copy onto a header.",
+          explanation: "The class (or one it is nested in) is declared generic by loaded RBS — core, stdlib, a gem " \
+                       "or `sig/` — and one of its type parameters has an upper bound or a default. sig-gen copies " \
+                       "a declaration's type parameters onto the header it writes only when every one is plain, " \
+                       "because a bound or default is a type spelled relative to the declaring file and can name " \
+                       "a different class under another nesting. A header without the parameters, or with ones " \
+                       "that differ, is rejected by rbs (`GenericParameterMismatchError`): the class, and every " \
+                       "class whose signature mentions it, would fail its definition build.",
+          next_step: "Declare the class in `sig/` with the declaration's own type parameters (`class Box[T < " \
+                     "Comparable]` ... `end`) and re-run; sig-gen then writes the members into that declaration."
+        ),
         "sig.skipped.inline-differs" => Entry.new(
           id: "sig.skipped.inline-differs",
           summary: "The method's inline declaration and its `sig/` declaration disagree; neither was changed.",

data/lib/rigor/sig_gen/type_name_qualification.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Rigor
+  module SigGen
+    # Issue [#2230](https://github.com/rigortype/rigor/issues/2230) — a rendered type names every class by its
+    # fully qualified name, but without the leading `::`: `Type::Nominal#erase_to_rbs` writes `Set[untyped]` for
+    # `::Set`. RBS resolves a relative name against the declaration it is written in, innermost namespace first,
+    # so inside `module Foo` that declares a `Foo::Set` the written `Set[untyped]` names `::Foo::Set`. A generic
+    # name then fails validation ("expects parameters [], but given args [untyped]"); a non-generic one types the
+    # method as the wrong class without a word.
+    #
+    # This anchors a name with `::` only where the namespace the member is written in, or one enclosing it,
+    # declares a constant with the name's first segment. Where nothing shadows it the spelling is unchanged, so
+    # output for the common case does not churn. The check is over every enclosing namespace of the owner, which
+    # covers both the nested `module Foo` / `class Bar` layout the writer emits and a compact `class Foo::Bar`
+    # header, and it may anchor a name RBS would have resolved correctly anyway: an anchored name is never wrong,
+    # while a missed one is.
+    module TypeNameQualification
+      module_function
+
+      NAMED_TYPES = [
+        RBS::Types::ClassInstance, RBS::Types::ClassSingleton, RBS::Types::Alias, RBS::Types::Interface
+      ].freeze
+      private_constant :NAMED_TYPES
+
+      # A capitalised word not already preceded by `::` or part of a longer identifier: the first segment of a
+      # relative class name. A cheap filter so the common case never reaches the parser.
+      RELATIVE_HEAD = /(?<![\w:])[A-Z]\w*/
+      private_constant :RELATIVE_HEAD
+
+      # @param rendered — an erased RBS type whose names each spell the class they mean from the top level.
+      # @param owner — the qualified name of the class or module the type is written in; nil at the top level.
+      # @param declared — called with a qualified name (`"Foo::Set"`); true when the project or the RBS
+      #   environment declares a constant there.
+      def qualify(rendered, owner, &declared)
+        namespaces = enclosing_namespaces(owner)
+        return rendered if namespaces.empty?
+        return rendered unless rendered.scan(RELATIVE_HEAD).any? { |head| shadowed?(head, namespaces, declared) }
+
+        positions = []
+        collect_positions(RBS::Parser.parse_type(rendered, require_eof: true), namespaces, declared, positions)
+        positions.sort.reverse_each.with_object(+rendered) { |position, out| out.insert(position, "::") }
+      rescue RBS::ParsingError
+        rendered
+      end
+
+      # `"A::B::C"` → `["A::B::C", "A::B", "A"]`: every namespace a relative name written in `A::B::C`'s
+      # declaration is looked up in before the top level.
+      def enclosing_namespaces(owner)
+        segments = owner.to_s.delete_prefix("::").split("::")
+        segments.size.downto(1).map { |n| segments.first(n).join("::") }
+      end
+
+      def collect_positions(type, namespaces, declared, positions)
+        if NAMED_TYPES.any? { |klass| type.is_a?(klass) } && !type.name.absolute?
+          head = (type.name.namespace.path.first || type.name.name).to_s
+          positions << type.location[:name].start_pos if shadowed?(head, namespaces, declared)
+        end
+        type.each_type { |child| collect_positions(child, namespaces, declared, positions) }
+      end
+
+      def shadowed?(head, namespaces, declared)
+        namespaces.any? { |namespace| declared.call("#{namespace}::#{head}") }
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/write_reporter.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../cli/json_document"
+
 require_relative "classification"
 
 module Rigor
@@ -18,10 +20,13 @@ module Rigor
       # @param refused — methods refused as `sig.skipped.inline-differs`; the JSON payload names them under
       #   `refused` (absent when there are none, so an ordinary payload is unchanged), and text mode leaves them
       #   to the command's stderr `REFUSED` lines.
-      def render_write(results:, format:, refused: [])
+      # @param left_bare — the generic classes whose bare headers the writer held back from the repair (#2605,
+      #   {Writer#left_bare}); the JSON payload names them under `left_bare` (absent when there are none), and text
+      #   mode prints one `generic header left bare` line each.
+      def render_write(results:, format:, refused: [], left_bare: [])
         case format
-        when "json" then render_write_json(results, refused)
-        when "text" then render_write_text(results)
+        when "json" then render_write_json(results, refused, left_bare)
+        when "text" then render_write_text_with_left_bare(results, left_bare)
         else raise ArgumentError, "unsupported format: #{format}"
         end
       end
@@ -32,14 +37,19 @@ module Rigor
       #
       # @param refused — the methods the generator refused to reconcile (`sig.skipped.inline-differs`):
       #   `sig/` is not up to date while one stands, and `--write` cannot fix it.
-      def render_check(results:, format:, refused: [])
+      #
+      # @param left_bare — as for {#render_write}; reported, but it does not make `sig/` out of date.
+      def render_check(results:, format:, refused: [], left_bare: [])
         stale = self.class.out_of_date(results)
         case format
         when "json"
-          @out.puts(JSON.pretty_generate({ up_to_date: stale.empty? && refused.empty?,
-                                           results: stale.map { |r| check_entry(r) },
-                                           refused: refused.map(&:to_h) }))
-        when "text" then render_check_text(stale, refused)
+          payload = { up_to_date: stale.empty? && refused.empty?, results: stale.map { |r| check_entry(r) },
+                      refused: refused.map(&:to_h) }
+          payload[:left_bare] = left_bare unless left_bare.empty?
+          @out.puts(JSON.pretty_generate(CLI::JsonDocument.stamp(payload)))
+        when "text"
+          render_check_text(stale, refused)
+          render_left_bare(left_bare)
         else raise ArgumentError, "unsupported format: #{format}"
         end
       end
@@ -89,6 +99,7 @@ module Rigor
           when :created, :updated then render_check_change(result)
           when :skipped_invalid_rbs then render_write_invalid(result)
           when :skipped_invalid_encoding then render_write_invalid_encoding(result)
+          when :skipped_unparseable then render_write_unparseable(result)
           end
         end
       end
@@ -103,12 +114,17 @@ module Rigor
         end
       end
 
-      def render_write_text(results)
+      # "No changes" only when nothing at all is reported: a header held back is news even when no file changed.
+      def render_write_text_with_left_bare(results, left_bare)
         if results.all? { |r| r.action == :noop && r.skipped.empty? }
-          @out.puts("No changes")
-          return
+          @out.puts("No changes") if left_bare.empty?
+        else
+          render_write_text(results)
         end
+        render_left_bare(left_bare)
+      end
 
+      def render_write_text(results)
         results.each do |result|
           case result.action
           when :created then render_write_created(result)
@@ -117,6 +133,7 @@ module Rigor
           when :skipped_outside_sig_root then render_write_skipped(result)
           when :skipped_invalid_rbs then render_write_invalid(result)
           when :skipped_invalid_encoding then render_write_invalid_encoding(result)
+          when :skipped_unparseable then render_write_unparseable(result)
           end
         end
       end
@@ -125,7 +142,29 @@ module Rigor
       # because "added 2" when one of them rewrote a line the project already had would understate the change.
       def applied_counts(result)
         added = "+#{result.applied.size - result.replaced.size}"
-        result.replaced.empty? ? added : "#{added}, replaced #{result.replaced.size}"
+        added = "#{added}, replaced #{result.replaced.size}" unless result.replaced.empty?
+        repaired = result.repaired_headers
+        repaired.empty? ? added : "#{added}, repaired #{repaired.size} generic header(s): #{repaired.join(', ')}"
+      end
+
+      # #2605 — one line per generic class the writer left with a bare header: every file holding one, and the
+      # parameter names the blocking bodies spell. rbs keeps rejecting the class until those names are anchored
+      # (`::E`) or the headers are given parameters by hand.
+      def render_left_bare(left_bare)
+        left_bare.each do |entry|
+          reasons = entry.fetch(:blocking).map { |blocking| left_bare_reason(blocking) }
+          @out.puts("generic header left bare: #{entry.fetch(:class)} in #{entry.fetch(:targets).join(', ')} " \
+                    "(#{reasons.join('; ')})")
+        end
+      end
+
+      def left_bare_reason(blocking)
+        if blocking.fetch(:reason) == "outside_sig_root"
+          "an opening outside the sig root at #{blocking.fetch(:target)}, which --write does not rewrite"
+        else
+          "#{blocking.fetch(:target)} names #{blocking.fetch(:names).join(', ')}, which the type parameter would " \
+            "capture"
+        end
       end
 
       def render_write_created(result)
@@ -193,10 +232,20 @@ module Rigor
         @out.puts("  Re-save the file as UTF-8 and re-run; sig-gen never modifies a file it cannot read faithfully.")
       end
 
-      def render_write_json(results, refused)
+      # The EXISTING target file does not parse as RBS, so the writer will not merge into it (#2480). Like the
+      # encoding refusal the fix is the user's: the file is quarantined whole by `rigor check` until it parses.
+      def render_write_unparseable(result)
+        @out.puts("REFUSED #{result.target_path} — the existing file was not updated")
+        @out.puts("  #{result.error}")
+        @out.puts("  Fix the syntax error and re-run; sig-gen never modifies a file it cannot parse.")
+      end
+
+      def render_write_json(results, refused, left_bare)
         payload = { results: results.map(&:to_h) }
         payload[:refused] = refused.map(&:to_h) unless refused.empty?
-        @out.puts(JSON.pretty_generate(payload))
+        # Absent when every bare generic header was repaired, so an ordinary payload is unchanged (#2605).
+        payload[:left_bare] = left_bare unless left_bare.empty?
+        @out.puts(JSON.pretty_generate(CLI::JsonDocument.stamp(payload)))
       end
     end
   end