rigortype 0.4.6 → 0.4.8

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,35 @@ 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
+
+      # A copy carrying more class shells: a class whose every member a later pass withheld still has to be
+      # declared for its subclasses' headers (#3029).
+      def with_class_shells(class_shells)
+        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

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../environment"
 require_relative "../project_environment"
+require_relative "../run_scoped_slots"
 require_relative "../scope"
 require_relative "../type"
 require_relative "../source/constant_path"
@@ -19,9 +20,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 +28,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).
@@ -58,10 +57,18 @@ module Rigor
         environment = build_environment(resolved)
         discovered_classes = preindex_source_classes
         observations = Hash.new { |h, k| h[k] = [] }
-        resolved.each do |path|
-          collect_from_file(path, environment, discovered_classes, observations)
+        # ADR-130 WD5 — with interface dispatch off, as {Generator#run} analyses: an argument read through a
+        # `Rigor::Plugin` interface member is not written into a parameter type either.
+        Inference::MethodDispatcher::RbsDispatch.without_interface_dispatch do
+          resolved.each do |path|
+            collect_from_file(path, environment, discovered_classes, observations)
+          end
         end
         observations.transform_values(&:freeze).freeze
+      ensure
+        # Issue #2869 — release this analysis's run-scoped slots, as every other entry point that runs one does, so
+        # a later run (the generator's, under its own interface-dispatch install) starts from none of them.
+        RunScopedSlots.release
       end
 
       # Whether `arg` names something {#collect} reads: a directory, or a `.rb` file. The CLI's

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/platform_guarded_files.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/node_children"
+
+module Rigor
+  module SigGen
+    # Issue #3035 — the files a sig-gen run must not read as ordinary definitions: every scanned `.rb`
+    # file Ruby loads ONLY through a platform-conditional `require` / `require_relative`.
+    #
+    # `stackprof.rb` opens with `if RUBY_ENGINE == 'truffleruby'` → `require "stackprof/truffleruby"`,
+    # and `truffleruby.rb` re-implements `StackProf.run` / `.results` as raising stubs — on MRI the C
+    # extension defines them. Scanning every `.rb` under `lib/` reads that stub file as an ordinary
+    # definition and proposes `StackProf.run -> bot` against a method whose real signature returns
+    # `Hash[Symbol, untyped]`.
+    #
+    # {.call} answers the guarded set from the resolved file list alone: it parses each file once,
+    # collects the literal `require` / `require_relative` sites, marks a site guarded when it sits
+    # inside a conditional whose predicate reads `RUBY_ENGINE`, `RUBY_PLATFORM` or `defined?(…)`,
+    # resolves each feature against the scanned set (`require_relative` against the file's own
+    # directory; `require` against the file's ancestor directories — the load-path approximation a
+    # gem's `lib/` root satisfies), and keeps the files whose EVERY incoming edge is guarded —
+    # directly, or through a file already known guarded (a helper `truffleruby.rb` requires
+    # unconditionally is still truffleruby-only). A file with no scanned require site is never
+    # guarded: an entry point, an autoload target or a `load`ed file cannot be told apart from a
+    # guarded one, and the unguarded reading is the one that emits.
+    #
+    # Limits, deliberately: require sites in files OUTSIDE the scanned set are invisible (a sibling
+    # the run did not read may require the file unguarded); `load`, `autoload` and computed features
+    # are not edges; a `require` sitting in the guard's own predicate — an `&&` / `||` operand, say —
+    # inherits the branch's guarded mark without the walk checking whether Ruby reaches it before the
+    # platform test decides; the `begin … rescue LoadError` fallback (`require "json"` else
+    # `require "json/pure"`) is not a platform guard, so both of its edges read unguarded; and a file
+    # that fails to parse poisons the whole answer — its require edges are unknowable, so {.call}
+    # returns an empty set rather than risk a false guarded verdict.
+    module PlatformGuardedFiles
+      # The constants a conditional predicate may read to make a require platform-dependent.
+      GUARD_CONSTANTS = %i[RUBY_ENGINE RUBY_PLATFORM].freeze
+      private_constant :GUARD_CONSTANTS
+
+      # The conditional forms whose whole subtree a platform predicate guards — `if` / `unless` in
+      # statement, modifier and ternary spelling, `case` and `case/in` on a guarded subject. Both
+      # branches count: `else` of `RUBY_ENGINE == 'x'` is `RUBY_ENGINE != 'x'`, still conditional.
+      CONDITIONALS = [Prism::IfNode, Prism::UnlessNode, Prism::CaseNode, Prism::CaseMatchNode].freeze
+      private_constant :CONDITIONALS
+
+      REQUIRE_CALLS = %i[require require_relative].freeze
+      private_constant :REQUIRE_CALLS
+
+      module_function
+
+      # @param paths — the `.rb` files the run will analyse, as spelled by the run.
+      # @param ruby_version — the Prism version to parse with (the configuration's `target_ruby`).
+      # @return a Set of `File.expand_path`'d paths that are required only under platform guards.
+      def call(paths, ruby_version: nil)
+        files = paths.map { |path| File.expand_path(path) }.uniq
+        known = files.to_set
+        edges = Hash.new { |hash, key| hash[key] = [] }
+        files.each do |file|
+          sites = require_sites(file, ruby_version, known)
+          return Set.new if sites.nil?
+
+          sites.each { |target, guarded| edges[target] << { from: file, guarded: guarded } }
+        end
+        guarded_closure(files, edges)
+      end
+
+      # Every `[target, guarded]` pair `file`'s literal require sites resolve to inside `known`;
+      # `nil` when the file does not parse (see the class comment for why that voids the answer).
+      def require_sites(file, ruby_version, known)
+        result = Prism.parse(File.read(file), filepath: file, version: ruby_version)
+        return nil if result.errors.any?
+
+        sites = []
+        walk_require_sites(result.value) do |node, guarded|
+          target = require_target(file, node, known)
+          sites << [target, guarded] if target
+        end
+        sites
+      end
+
+      # An explicit stack, not recursion: a require site deep in a generated file must not exhaust it.
+      def walk_require_sites(root, &block)
+        stack = [[root, false]]
+        until stack.empty?
+          node, guarded = stack.pop
+          next unless node.is_a?(Prism::Node)
+
+          block.call(node, guarded) if require_call?(node)
+          child_guarded = guarded || platform_conditional?(node)
+          node.rigor_each_child { |child| stack << [child, child_guarded] }
+        end
+      end
+
+      # A `require "feature"` / `require_relative "feature"` with one string literal and no receiver —
+      # the same strictness {Analysis::RequireRelativeClosure} reads `require_relative` with.
+      def require_call?(node)
+        return false unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+        return false unless REQUIRE_CALLS.include?(node.name)
+
+        arguments = node.arguments&.arguments
+        arguments&.size == 1 && arguments.first.is_a?(Prism::StringNode)
+      end
+
+      # Whether `node` is a conditional whose predicate makes what it guards platform-dependent: a
+      # `RUBY_ENGINE` / `RUBY_PLATFORM` read or a `defined?(…)` anywhere in it.
+      def platform_conditional?(node)
+        return false unless CONDITIONALS.any? { |klass| node.is_a?(klass) }
+
+        predicate = node.predicate
+        !predicate.nil? && platform_expression?(predicate)
+      end
+
+      # Iterative like {#walk_require_sites}: a predicate can chain thousands of `||` operands. A hit is
+      # the only answer — a constant that is NOT a guard (`RUBY_VERSION`, `ENV`, a namespaced path) does
+      # not end the walk, or `RUBY_ENGINE == "x" && RUBY_VERSION >= "y"` would read unguarded on the
+      # strength of which operand the stack pops first.
+      def platform_expression?(root)
+        stack = [root]
+        until stack.empty?
+          node = stack.pop
+          next unless node.is_a?(Prism::Node)
+          return true if node.is_a?(Prism::DefinedNode)
+          return true if node.is_a?(Prism::ConstantReadNode) && GUARD_CONSTANTS.include?(node.name)
+          # `::RUBY_ENGINE` names the same constant; `Foo::RUBY_ENGINE` is a different one.
+          return true if node.is_a?(Prism::ConstantPathNode) && node.parent.nil? &&
+                         GUARD_CONSTANTS.include?(node.name)
+
+          node.rigor_each_child { |child| stack << child }
+        end
+        false
+      end
+
+      # The scanned file `node`'s feature resolves to, or nil when it names nothing the run reads
+      # (a gem, a `.so`, a computed path's sibling).
+      def require_target(site_file, node, known)
+        feature = node.arguments.arguments.first.unescaped
+        feature += ".rb" unless feature.end_with?(".rb")
+        if node.name == :require_relative
+          candidate = File.expand_path(feature, File.dirname(site_file))
+          return candidate if known.include?(candidate)
+
+          return nil
+        end
+
+        # `require` resolves through the load path; the file's own directory upward is the
+        # approximation that finds `lib/stackprof/truffleruby.rb` for `require "stackprof/truffleruby"`
+        # in `lib/stackprof.rb`, nearest ancestor first.
+        dir = File.dirname(site_file)
+        loop do
+          candidate = File.expand_path(feature, dir)
+          return candidate if known.include?(candidate)
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      # The fixpoint: a file is guarded-only when it has at least one scanned require edge and every
+      # edge reaching it is either syntactically guarded or issued from a file already guarded-only.
+      def guarded_closure(files, edges)
+        guarded = Set.new
+        loop do
+          added = false
+          files.each do |file|
+            next if guarded.include?(file)
+
+            incoming = edges[file]
+            next if incoming.empty?
+            next unless incoming.all? { |edge| edge[:guarded] || guarded.include?(edge[:from]) }
+
+            guarded << file
+            added = true
+          end
+          break unless added
+        end
+        guarded
+      end
+    end
+  end
+end

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)