rigortype 0.4.6 → 0.4.8

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.",
@@ -136,6 +149,38 @@ module Rigor
           next_step: "Generate signatures for the overriding subclass too — widen the `sig-gen` path set to " \
                      "cover it — and the parent's declaration becomes safe to emit."
         ),
+        "sig.skipped.overridden-bot" => Entry.new(
+          id: "sig.skipped.overridden-bot",
+          summary: "The method's body never returns, and the analysed code overrides the method.",
+          explanation: "The inferred return is `bot`, but the analysed code defines the method again, with `def` " \
+                       "or `define_method`: a subclass (signed or not), a class that includes the method's module, " \
+                       "a module included later or prepended, or an extending class's own singleton method. " \
+                       "`bot` describes only the base body the overrides replace, and every override returns a " \
+                       "value, so the declaration would contradict each of them (#3029).",
+          next_step: "Declare the return every implementation shares (often `untyped` or the overrides' common " \
+                     "type) by hand in `sig/`."
+        ),
+        "sig.skipped.abstract-method" => Entry.new(
+          id: "sig.skipped.abstract-method",
+          summary: "The method is abstract: its body only raises an error asking for an implementation.",
+          explanation: "The body ends in `raise NotImplementedError`, in an error class named `Abstract...` or " \
+                       "`NotImplemented...`, or in a raise whose message asks for the method to be implemented, " \
+                       "defined or overridden. Its inferred return is `bot`, but the method is meant to be " \
+                       "replaced, and the replacements may live outside the analysed code, as in a plugin gem " \
+                       "(#3029).",
+          next_step: "Declare the return the implementations must provide by hand in `sig/`."
+        ),
+        "sig.skipped.template-method" => Entry.new(
+          id: "sig.skipped.template-method",
+          summary: "The method's `bot` return may come only from calling an overridden or abstract method.",
+          explanation: "The inferred return is `bot`, and the body does not end in a direct `raise`, `fail`, " \
+                       "`throw`, `exit` or `abort`. It calls a method the analysed code overrides or declares " \
+                       "abstract, directly or through a chain of self-dispatched calls, so the `bot` may be only " \
+                       "the base body of that call, which an override replaces at run time. The call is matched " \
+                       "by name, whatever its receiver (#3029).",
+          next_step: "Declare the return by hand in `sig/`, usually the return the overridden hook's " \
+                     "implementations share."
+        ),
         "sig.skipped.top-level-def" => Entry.new(
           id: "sig.skipped.top-level-def",
           summary: "A top-level `def` defines a private `Object` method, and sig-gen writes no signature for it.",
@@ -158,6 +203,21 @@ module Rigor
                        "writes neither rather than guess (#1968).",
           next_step: "Move the visibility call to the module body's own statements, or name the methods it " \
                      "should cover (`public :name`, `module_function :name`), so the reading is certain."
+        ),
+        "sig.skipped.platform-guarded" => Entry.new(
+          id: "sig.skipped.platform-guarded",
+          summary: "The method is defined in a file loaded only under a platform guard, so its proposal was withheld.",
+          explanation: "The file is `require`d / `require_relative`d only inside a conditional on " \
+                       "`RUBY_ENGINE`, `RUBY_PLATFORM` or `defined?(…)`, so it is not an ordinary definition " \
+                       "for every platform — the shape is `if RUBY_ENGINE == 'truffleruby'` guarding a " \
+                       "pure-Ruby fallback whose real methods a C extension provides elsewhere. sig-gen " \
+                       "withholds the proposal when another scanned file also defines the method (the " \
+                       "guarded copy would compete with or duplicate the definition this platform loads), " \
+                       "or when the inferred return is `bot` — the shape a raising stub takes, and never a " \
+                       "contract worth writing from a file the current engine may never read (#3035).",
+          next_step: "Declare the method for the platform the project targets — hand-write the `sig/` " \
+                     "entry, or cover the file that defines it on this platform in the `sig-gen` paths — " \
+                     "rather than taking the guarded file's stub as the contract."
         )
       }.freeze
 

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

data/lib/rigor/sig_gen/write_result.rb

@@ -11,7 +11,7 @@ module Rigor
     # - `target_path` — `.rbs` file the writer was responsible for (`nil` when the source path falls outside
     #   the project signature tree, in which case `action` is `:skipped_outside_sig_root`).
     # - `action` — one of `:created` / `:updated` / `:noop` / `:skipped_outside_sig_root` /
-    #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding`.
+    #   `:skipped_invalid_rbs` / `:skipped_invalid_encoding` / `:skipped_unparseable`.
     # - `applied` — the {MethodCandidate}s that actually landed on disk.
     # - `replaced` — the subset of `applied` that replaced an existing declaration rather than adding one
     #   (`--overwrite`'s tighter returns, and inline updates).
@@ -23,16 +23,20 @@ module Rigor
     #   target declaration already carries annotations, so its bytes were left alone
     #   (`sig.effect.left-unreadable`; see {Writer#splice_annotations}). The signature line itself was
     #   still updated.
+    # - `repaired_headers` — the existing class or module headers the writer gave a generic class's type
+    #   parameters (`"Array[unchecked out E]"`), because the file opened it with none (#2580).
     # - `error` — the refusal cause, when `action` is a refusal: for `:skipped_invalid_rbs` the file the writer
     #   assembled does not parse, so it was NOT written (writing it would poison the project's sig tree — the
     #   consumer quarantines an unparseable `.rbs`, taking every other type in that file down with it); for
     #   `:skipped_invalid_encoding` the EXISTING target file is not valid UTF-8, so the writer refuses to merge
-    #   into content it cannot read faithfully.
+    #   into content it cannot read faithfully; for `:skipped_unparseable` the EXISTING target file does not parse
+    #   as RBS, so the writer refuses to merge into it (#2480).
     class WriteResult
-      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error, :left_unreadable, :replaced
+      attr_reader :source_path, :target_path, :action, :applied, :skipped, :error, :left_unreadable, :replaced,
+                  :repaired_headers
 
       def initialize(source_path:, target_path:, action:, applied: [], skipped: [], error: nil, # rubocop:disable Metrics/ParameterLists
-                     left_unreadable: [], replaced: [])
+                     left_unreadable: [], replaced: [], repaired_headers: [])
         @source_path = source_path
         @target_path = target_path
         @action = action
@@ -41,6 +45,7 @@ module Rigor
         @error = error
         @left_unreadable = left_unreadable.freeze
         @replaced = replaced.freeze
+        @repaired_headers = repaired_headers.freeze
         freeze
       end
 
@@ -51,14 +56,20 @@ module Rigor
           action: action.to_s,
           applied: applied.map(&:to_h),
           skipped: skipped.map { |c, reason| c.to_h.merge(write_skip_reason: reason.to_s) }
-        }.tap do |h|
-          h[:error] = error if error
-          # Absent when nothing was replaced, so a run that only adds lines keeps its pre-#1076 payload.
-          h[:replaced] = replaced.map(&:to_h) unless replaced.empty?
-          # Absent rather than empty when nothing was left: an effects-off payload stays byte-identical
-          # to a pre-#391 one.
-          h[:effect_left_unreadable] = left_unreadable.map(&:to_h) unless left_unreadable.empty?
-        end
+        }.tap { |h| add_optional_entries(h) }
+      end
+
+      private
+
+      def add_optional_entries(hash)
+        hash[:error] = error if error
+        # Absent when nothing was replaced, so a run that only adds lines keeps its pre-#1076 payload.
+        hash[:replaced] = replaced.map(&:to_h) unless replaced.empty?
+        # Absent when no header was repaired (#2580), for the same reason.
+        hash[:repaired_headers] = repaired_headers unless repaired_headers.empty?
+        # Absent rather than empty when nothing was left: an effects-off payload stays byte-identical
+        # to a pre-#391 one.
+        hash[:effect_left_unreadable] = left_unreadable.map(&:to_h) unless left_unreadable.empty?
       end
     end
   end