rigortype 0.3.6 → 0.3.8

data/lib/rigor/cli/coverage_command.rb

@@ -217,24 +217,23 @@ module Rigor
       # class. Tier 1 seeds unconditionally because it only reclassifies sites it already counted; Tier 2 adds
       # sites to a denominator `--threshold` gates CI on, which is why only the latter is gated on a feature id.
       def scope_with_inferred_params(paths, configuration, environment, workers)
-        base = Scope.empty(environment: environment)
-        seed = {}
-
-        discovered = Inference::ScopeIndexer.discovered_classes_for_paths(paths)
-        seed[:discovered_classes] = discovered unless discovered.empty?
-
-        table = Inference::ParameterInferenceCollector.collect(
-          files: paths, environment: environment, target_ruby: configuration.target_ruby, workers: workers
+        CoverageScan.discovery_seeded_scope(
+          files: paths, configuration: configuration, environment: environment,
+          parameter_inference: true, workers: workers
         )
-        seed[:param_inferred_types] = table unless table.empty?
-
-        return base if seed.empty?
-
-        base.with_discovery(base.discovery.with(**seed))
       end
 
+      # Issue #686 — an unmeasured file fails the build the way a parse error already does, and for the same
+      # reason: the command could not measure part of what it was asked about, so its ratio is an answer to
+      # a smaller question than the user asked. Deliberately NOT routed through `--threshold`, which the
+      # line below applies to a ratio: a crashed file's mutants leave `killed + survived` at zero, the
+      # project ratio is then computed over the files that DID work, and a run that measured nothing at all
+      # came out at 1.0 and passed every threshold. It is also deliberately not the `harness_errors` count,
+      # which #264 keeps out of the exit code on purpose — a few rescued mutants are the transient that
+      # bucket exists to make visible, while a wholly unmeasured FILE is not a transient.
       def determine_protection_exit(report, options)
         return 1 unless report.parse_errors.empty?
+        return 1 if unmeasured_files_in(report).positive?
 
         threshold = options[:threshold]
         return 0 if threshold.nil?
@@ -242,6 +241,12 @@ module Rigor
         report.ratio < threshold ? 1 : 0
       end
 
+      # Issue #686 — the one reader of the count, shared with the stderr warning. The Tier-1 protection
+      # report has no such notion, so a report without the field reads as zero rather than erroring.
+      def unmeasured_files_in(report)
+        report.respond_to?(:unmeasured_files) ? report.unmeasured_files : 0
+      end
+
       def usage_error
         @err.puts("coverage: at least one path is required")
         @err.puts(USAGE)
@@ -254,11 +259,11 @@ module Rigor
 
       # The protection scan must see the same receiver types `rigor check` does — including plugin-contributed
       # `dynamic_return` types (a controller's `params` → `ActionController::Parameters`, a `Model.where` →
-      # `ActiveRecord::Relation[Model]`). The bare `CoverageScan.project_environment` carries only the RBS environment
-      # (no plugin registry), so every plugin-typed receiver reads `Dynamic` and its dispatch site is miscounted as
-      # *unprotected* — a systematic undercount of what Rigor actually types on a plugin-using project.
-      # `ProjectContext` builds the plugin-aware environment (registry materialised + the per-run prepare pass that
-      # primes producers like the controller / model index) exactly as the LSP and the runner do.
+      # `ActiveRecord::Relation[Model]`). A bare RBS environment carries no plugin registry, so every plugin-typed
+      # receiver reads `Dynamic` and its dispatch site is miscounted as *unprotected* — a systematic undercount of
+      # what Rigor actually types on a plugin-using project. `ProjectContext` builds the plugin-aware environment
+      # (registry materialised + the per-run prepare pass that primes producers like the controller / model index)
+      # exactly as the LSP, the runner, and — since #513 — the precision path all do.
       def plugin_aware_environment(configuration)
         LanguageServer::ProjectContext.new(configuration: configuration).environment
       end

data/lib/rigor/cli/coverage_mutation.rb

@@ -9,6 +9,8 @@ require_relative "../protection/dependency_closure"
 require_relative "../protection/discovery_seed"
 require_relative "../protection/mutation_cache"
 
+require_relative "measurement_integrity_warning"
+
 module Rigor
   class CLI
     # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic protection paths, factored out of
@@ -43,17 +45,13 @@ module Rigor
 
       private
 
-      # @param report [MutationProtectionReport, FusedProtectionReport] — both expose `total_harness_errors`.
+      # Both measurement-integrity warnings, and the escalation rule between them, live in
+      # {MeasurementIntegrityWarning}. Only the floor stays here: it is this command's policy, and
+      # `coverage_command_spec` reads it off this module.
+      #
+      # @param report [MutationProtectionReport, FusedProtectionReport]
       def warn_harness_errors(report)
-        count = report.total_harness_errors
-        return if count < HARNESS_ERROR_WARN_FLOOR
-
-        @err.puts(
-          "coverage: #{count} mutants failed inside the measurement harness (\"harness_errors\", " \
-          "at/above the #{HARNESS_ERROR_WARN_FLOOR}-mutant floor) — excluded from the ratio like a " \
-          "parse-invalid mutant, but this many suggests a harness defect rather than one-off noise. " \
-          "Investigate before trusting --threshold on this run."
-        )
+        MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
 
       # The cross-file knowledge Tier 2 measures with — the #253 gate, and the ONLY place in this feature that
@@ -262,13 +260,11 @@ module Rigor
       # the two sets were assembled.
       #
       # The two cache phases each get their OWN {Cache::FileDigest.with_run} scope and the MEASUREMENT sits
-      # between them, deliberately: that scope installs a per-path digest memo, and {Protection::ClosureKillOracle}
-      # rewrites one process-private temp file per mutant and digests it through a buffer binding. A memo
-      # spanning the measurement would hand every mutant after the first the FIRST one's digest, the mutated
-      # file's discovery bundle would never be re-walked, and the run would report zero cross-file kills — a
-      # plausible-looking number rather than an error. The oracle's own comment states the same invariant from
-      # the other side. The cost of two scopes is one extra SHA-256 per cached file, against a measurement
-      # that is hundreds of analyses.
+      # between them, deliberately: that scope installs a per-path digest memo. {Protection::ClosureKillOracle}
+      # now writes each mutant to a fresh block-scoped path, so a memo spanning the measurement could no
+      # longer serve one mutant another's digest — but keeping the measurement outside any memo scope stays
+      # correct by construction rather than by the oracle's path discipline, and costs only one extra
+      # SHA-256 per cached file against a measurement that is hundreds of analyses.
       def measure_mutation_files(paths, cache:, scanner:, context:, configuration:, workers:)
         cached = with_digest_run(configuration) { paths.to_h { |path| [path, cache.fetch(path)] }.compact }
         pending = paths - cached.keys

data/lib/rigor/cli/coverage_scan.rb

@@ -4,7 +4,11 @@ require "prism"
 
 require_relative "../configuration"
 require_relative "../environment"
+require_relative "../inference/parameter_inference_collector"
 require_relative "../inference/precision_scanner"
+require_relative "../inference/scope_indexer"
+require_relative "../language_server/project_context"
+require_relative "../protection/discovery_seed"
 require_relative "../scope"
 require_relative "coverage_report"
 
@@ -20,19 +24,56 @@ module Rigor
       # @param files [Array<String>] explicit `.rb` file paths to scan.
       # @param configuration [Rigor::Configuration]
       # @return [Rigor::CLI::CoverageReport]
+      #
+      # Issue #513 — the environment is PLUGIN-AWARE (`LanguageServer::ProjectContext`, the same builder
+      # `--protection` uses), not the bare RBS environment this path carried until 2026-09-01. Without the
+      # plugin registry every plugin-typed receiver read `Dynamic` and the precision ratio understated the
+      # engine by ~1.2 points on a Rails target — the defect the protection path documented and fixed for
+      # itself on 2026-07-04, never applied here.
       def precision_report(files:, configuration:)
-        scope = Scope.empty(environment: project_environment(configuration))
+        scope = discovery_seeded_scope(
+          files: files,
+          configuration: configuration,
+          environment: LanguageServer::ProjectContext.new(configuration: configuration).environment,
+          parameter_inference: configuration.parameter_inference
+        )
         scanner = Inference::PrecisionScanner.new(scope: scope)
         accumulator = CoverageAccumulator.new
         files.each { |path| scan_into(path, scanner, accumulator, configuration) }
         accumulator.to_report(files, {})
       end
 
-      def project_environment(configuration)
-        Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
-        )
+      # The cross-file facts a scan must see to report the types the engine actually infers, rather than the types a
+      # file-at-a-time walk can reach on its own.
+      #
+      # Issue #513 — the seed is the FULL check-walk bundle (`Protection::DiscoverySeed.discovery_tables`: classes,
+      # def nodes and sources for both kinds, superclasses, includes, visibilities, methods, and the Data / Struct
+      # member layouts), not just `discovered_classes`. The two-table seed #505 introduced closed the biggest part of
+      # the gap and left the rest: without the def-node / ancestry tables every cross-file call to a source-inferred
+      # project method measured as unresolved while `rigor check` resolves it — +0.27pp on redmine, +0.77pp on
+      # mastodon from the tables alone.
+      #
+      # `parameter_inference` is a parameter rather than a config read because the two callers want different answers:
+      # the precision lens must mirror the walk it describes (`check` leaves the table empty unless
+      # `parameter_inference:` is on, ADR-67 WD6a), while `--protection` seeds it unconditionally by ADR-67's own
+      # wiring — it only ever reclassifies sites it already counted.
+      #
+      # @return [Rigor::Scope]
+      def discovery_seeded_scope(files:, configuration:, environment:, parameter_inference:, workers: nil)
+        base = Scope.empty(environment: environment)
+        seed = Protection::DiscoverySeed.discovery_tables(files).dup
+
+        if parameter_inference
+          table = Inference::ParameterInferenceCollector.collect(
+            files: files, environment: environment, target_ruby: configuration.target_ruby,
+            workers: workers || configuration.parallel_workers
+          )
+          seed[:param_inferred_types] = table unless table.empty?
+        end
+
+        return base if seed.empty?
+
+        base.with_discovery(base.discovery.with(**seed))
       end
 
       # Parses one file and feeds the scan result (or a parse-error record) into `accumulator`. `scanner` /

data/lib/rigor/cli/fused_protection_renderer.rb

@@ -27,17 +27,34 @@ module Rigor
       end
 
       def render_text(report)
-        pct = (report.ratio * 100).round(1)
+        pct = report.ratio ? (report.ratio * 100).round(1) : nil
         @out.puts "Fused protection (static type ∪ dynamic test)"
-        @out.puts "  protected: #{report.protected_total} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "  protected: #{report.protected_total} / #{report.grand_total}#{ratio_suffix(pct)}"
         @out.puts "    by type:  #{report.total_type_killed}"
         @out.puts "    by test:  #{report.total_test_killed}  (type-survivors a test caught)"
         @out.puts "  unprotected: #{report.total_unprotected}  (neither — add a type or a test)"
+        render_unmeasured_files(report)
         render_harness_errors(report)
         render_unprotected(report)
         render_files(report)
       end
 
+      # Issue #686 — see {MutationProtectionRenderer#ratio_suffix}.
+      def ratio_suffix(pct)
+        return "  (not measured)" if pct.nil?
+
+        "  (#{pct}%)"
+      end
+
+      # Issue #686 — see {MutationProtectionRenderer#render_unmeasured_files}.
+      def render_unmeasured_files(report)
+        count = report.unmeasured_files
+        return if count.zero?
+
+        @out.puts "  unmeasured files: #{count} — every mutation of them failed inside the measurement " \
+                  "harness, so they are not in the ratio above"
+      end
+
       # #264 — see {MutationProtectionRenderer#render_harness_errors}; surfaced only when non-zero.
       def render_harness_errors(report)
         count = report.total_harness_errors

data/lib/rigor/cli/fused_protection_report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../protection/measurement_integrity"
+
 module Rigor
   class CLI
     # ADR-70 — aggregates per-file {Protection::MutationScanner::FusedFileResult} into a project-level **fused**
@@ -14,6 +16,13 @@ module Rigor
       def initialize(path:, type_killed:, test_killed:, unprotected:, ratio:, harness_errors: 0)
         super
       end
+
+      # Issue #686 — see {Rigor::CLI::FileEffectiveness#unmeasured?}.
+      def unmeasured?
+        !Protection::MeasurementIntegrity.measured?(
+          total: type_killed + test_killed + unprotected, harness_errors: harness_errors
+        )
+      end
     end
     UnprotectedBreakage = Data.define(:method_name, :count, :examples)
 
@@ -23,19 +32,31 @@ module Rigor
       def total_unprotected = files.sum(&:unprotected)
       def grand_total = total_type_killed + total_test_killed + total_unprotected
       def protected_total = total_type_killed + total_test_killed
-      def ratio = grand_total.zero? ? 1.0 : protected_total.to_f / grand_total
+
+      # Issue #686 review (second pass) — see {MutationProtectionReport#ratio}.
+      def ratio
+        return nil if Protection::MeasurementIntegrity.ratio_unmeasurable?(
+          grand_total: grand_total, unmeasured_files: unmeasured_files
+        )
+
+        grand_total.zero? ? 1.0 : protected_total.to_f / grand_total
+      end
 
       # #264 — stays OUT of `grand_total`/`ratio`, exactly like the plain mutation report.
       def total_harness_errors = files.sum(&:harness_errors)
 
+      # Issue #686 — see {Rigor::CLI::MutationProtectionReport#unmeasured_files}.
+      def unmeasured_files = files.count(&:unmeasured?)
+
       def to_h
         {
           "mode" => "protection-fused",
           "type_killed" => total_type_killed,
           "test_killed" => total_test_killed,
           "unprotected" => total_unprotected,
-          "protected_ratio" => ratio.round(4),
+          "protected_ratio" => ratio&.round(4),
           "harness_errors" => total_harness_errors,
+          "unmeasured_files" => unmeasured_files,
           "files" => files.map do |f|
             { "path" => f.path, "type_killed" => f.type_killed, "test_killed" => f.test_killed,
               "unprotected" => f.unprotected, "ratio" => f.ratio.round(4), "harness_errors" => f.harness_errors }

data/lib/rigor/cli/measurement_integrity_warning.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # The stderr half of "did this measurement actually happen" for `rigor coverage --protection --mutation`.
+    #
+    # Two counts, escalating, and the difference between them is the whole point:
+    #
+    # - `harness_errors` (#264) counts MUTANTS the harness rescued. Advisory and floored — a few are the
+    #   transient the bucket exists to make visible, and `determine_protection_exit` deliberately ignores
+    #   them so a `--threshold` build does not start failing for a reason unrelated to the ratio it pins.
+    # - `unmeasured_files` (#686) counts FILES where nothing could be measured at all, because the clean
+    #   baseline itself came back from a crashed analysis. No floor and not advisory: the ratio then answers
+    #   a smaller question than the user asked, `determine_protection_exit` fails the run, and this says so.
+    #   Without it, `killed + survived == 0` borrowed the vacuous-file convention's 1.0 and a run that
+    #   measured nothing printed 100% and passed every threshold.
+    #
+    # Extracted from {CoverageMutation} rather than inlined there: that module sits at its length budget, and
+    # a warning pair with its own escalation rule is a thing worth naming anyway.
+    module MeasurementIntegrityWarning
+      module_function
+
+      # @param report [MutationProtectionReport, FusedProtectionReport] both expose the two counts.
+      # @param err [IO] the stream to warn on.
+      # @param floor [Integer] {CoverageMutation::HARNESS_ERROR_WARN_FLOOR}.
+      # @return [void]
+      def emit(report, err:, floor:)
+        lines_for(report, floor: floor).each { |line| err.puts(line) }
+      end
+
+      # @return [Array<String>] the warnings this report earns, widest consequence first.
+      def lines_for(report, floor:)
+        lines = []
+        unmeasured = report.respond_to?(:unmeasured_files) ? report.unmeasured_files : 0 # see CoverageCommand
+        lines << unmeasured_line(unmeasured) if unmeasured.positive?
+        harness_errors = report.total_harness_errors
+        lines << harness_error_line(harness_errors, floor) if harness_errors >= floor
+        lines
+      end
+
+      def unmeasured_line(count)
+        "coverage: #{count} file(s) could not be measured at all — every mutation of them failed inside " \
+          "the measurement harness, typically because Rigor's own analysis crashed while re-analysing " \
+          "them. They contribute nothing to the ratio, so the effectiveness above is measured over the " \
+          "REST of the project. Exiting non-zero: a ratio over part of what you asked about must not read " \
+          "as a pass."
+      end
+
+      def harness_error_line(count, floor)
+        "coverage: #{count} mutants failed inside the measurement harness (\"harness_errors\", at/above " \
+          "the #{floor}-mutant floor) — excluded from the ratio like a parse-invalid mutant, but this many " \
+          "suggests a harness defect rather than one-off noise. Investigate before trusting --threshold " \
+          "on this run."
+      end
+    end
+  end
+end

data/lib/rigor/cli/mutation_protection_renderer.rb

@@ -26,15 +26,35 @@ module Rigor
       end
 
       def render_text(report)
-        pct = (report.ratio * 100).round(1)
+        pct = report.ratio ? (report.ratio * 100).round(1) : nil
         @out.puts "Type-protection effectiveness (Tier 2 — mutation kill rate)"
-        @out.puts "  caught breakages: #{report.total_killed} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "  caught breakages: #{report.total_killed} / #{report.grand_total}#{ratio_suffix(pct)}"
         @out.puts "  (effectiveness = when a type-visible bug was introduced, Rigor caught it)"
+        render_unmeasured_files(report)
         render_harness_errors(report)
         render_missed(report)
         render_files(report)
       end
 
+      # Issue #686 — `0 / 0` is `ratio` 1.0 by the vacuous-file convention, and printing "100.0%" over a run
+      # that measured nothing is the exact shape this issue exists to end. When nothing was measured AND a
+      # file went unmeasured, the percentage is withheld rather than invented.
+      def ratio_suffix(pct)
+        return "  (not measured)" if pct.nil?
+
+        "  (#{pct}%)"
+      end
+
+      # Issue #686 — the count that makes the command exit non-zero, on stdout beside the ratio it qualifies
+      # (the stderr twin in `CoverageMutation#warn_unmeasured_files` carries the explanation).
+      def render_unmeasured_files(report)
+        count = report.unmeasured_files
+        return if count.zero?
+
+        @out.puts "  unmeasured files: #{count} — every mutation of them failed inside the measurement " \
+                  "harness, so they are not in the ratio above"
+      end
+
       # #264 — surfaced only when non-zero: a harness-level failure is a defect in the measurement itself, not
       # in the code being measured, and a clean run should not carry a permanent line about a bucket that is
       # always empty.

data/lib/rigor/cli/mutation_protection_report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../protection/measurement_integrity"
+
 module Rigor
   class CLI
     # ADR-63 Tier 2 — aggregates per-file {Protection::MutationScanner} results into a project-level *effectiveness*
@@ -16,6 +18,13 @@ module Rigor
       def initialize(path:, killed:, survived:, ratio:, harness_errors: 0)
         super
       end
+
+      # Issue #686 — the file measured the HARNESS, not the code: every mutant it had landed in
+      # `harness_errors`, so `killed + survived` is zero for a reason that is not "there was nothing to
+      # measure". `ratio` is 0.0 here rather than the vacuous 1.0, and this is what the exit gate reads.
+      def unmeasured?
+        !Protection::MeasurementIntegrity.measured?(total: killed + survived, harness_errors: harness_errors)
+      end
     end
     MissedBreakage = Data.define(:method_name, :count, :examples)
 
@@ -23,21 +32,41 @@ module Rigor
       def total_killed = files.sum(&:killed)
       def total_survived = files.sum(&:survived)
       def grand_total = total_killed + total_survived
-      def ratio = grand_total.zero? ? 1.0 : total_killed.to_f / grand_total
+
+      # Issue #686 review (second pass) — `nil`, not 1.0, when nothing was measured and something failed
+      # trying. The text renderer already withheld the percentage; JSON did not, so a CI gate reading
+      # `effectiveness_ratio` still saw 100% on a run that measured nothing — the same defect one channel
+      # over. An empty project (nothing to measure, nothing failed) stays vacuously 1.0.
+      def ratio
+        return nil if Protection::MeasurementIntegrity.ratio_unmeasurable?(
+          grand_total: grand_total, unmeasured_files: unmeasured_files
+        )
+
+        grand_total.zero? ? 1.0 : total_killed.to_f / grand_total
+      end
 
       # #264 — a harness-level failure count, summed across files. Stays OUT of `grand_total`/`ratio` exactly
       # like a parse error: it is not a measurement of the code.
       def total_harness_errors = files.sum(&:harness_errors)
 
+      # Issue #686 — files where NOTHING could be measured. Distinct from `total_harness_errors`, which
+      # counts mutants and rightly tolerates a few (#264's floor): one wholly unmeasured file already means
+      # the ratio is computed over a smaller project than the user asked about, so this gates the exit and
+      # the mutant count does not.
+      def unmeasured_files = files.count(&:unmeasured?)
+
       def to_h
         {
           "mode" => "mutation",
           "killed" => total_killed,
           "survived" => total_survived,
-          "effectiveness_ratio" => ratio.round(4),
+          "effectiveness_ratio" => ratio&.round(4),
           # #264 — unconditional: a JSON consumer (e.g. a CI gate) must be able to check this every run, not
           # only when a text renderer decided it was worth a line.
           "harness_errors" => total_harness_errors,
+          # Issue #686 — unconditional for the same reason `harness_errors` is: a CI gate reading JSON must
+          # be able to see that part of the project was never measured, on every run.
+          "unmeasured_files" => unmeasured_files,
           "files" => files.map do |f|
             { "path" => f.path, "killed" => f.killed, "survived" => f.survived,
               "ratio" => f.ratio.round(4), "harness_errors" => f.harness_errors }

data/lib/rigor/cli/sig_gen_command.rb

@@ -33,6 +33,12 @@ module Rigor
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
+      # The skip reasons {#report_skipped} counts. The two left out each have a detailed report of their own
+      # ({#report_unrenderable}, {#report_unresolvable_superclasses}), so a method never shows up in two tallies.
+      SUMMARISED_SKIP_REASONS = (SigGen::Classification::SKIP_DIAGNOSTIC_IDS.keys -
+                                 %i[unrenderable_rbs unresolvable_superclass]).freeze
+      private_constant :SUMMARISED_SKIP_REASONS
+
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
@@ -54,12 +60,36 @@ module Rigor
                    dispatch_print_or_diff(candidates, mode, options)
                    0
                  end
+        report_skipped(candidates, options)
         report_unrenderable(generator.unrenderable)
+        report_unresolvable_superclasses(generator.unresolvable_superclasses)
         status
       end
 
       private
 
+      # Issue #778 — one stderr line per run saying how many methods the generator declined and why, so a
+      # method missing from the output is never a silent absence. Text mode only: under `--format=json` every
+      # skipped row is already in the payload with its `skip_reason`, and stderr stays clean for the consumer.
+      # Per-method lines would be noise at project scale; the JSON payload is where each one is named.
+      def report_skipped(candidates, options)
+        return unless options.fetch(:format) == "text"
+
+        counts = candidates.each_with_object(Hash.new(0)) do |candidate, acc|
+          next unless candidate.classification == SigGen::Classification::SKIPPED
+          next unless SUMMARISED_SKIP_REASONS.include?(candidate.skip_reason)
+
+          acc[candidate.skip_reason] += 1
+        end
+        return if counts.empty?
+
+        breakdown = counts.map { |reason, n| "#{SigGen::Classification::SKIP_DIAGNOSTIC_IDS.fetch(reason)}: #{n}" }
+        @err.puts(
+          "rigor sig-gen: skipped #{counts.values.sum} method(s) it could not type or would not overwrite " \
+          "(#{breakdown.join(', ')}). Run with --format=json to see each one with its skip_reason."
+        )
+      end
+
       # A method whose rendered RBS does not parse is a Rigor rendering defect, not a fact about the user's
       # code — the generator skipped it (so the rest of the signatures are still usable and still valid), but
       # staying silent would leave the user with a quietly incomplete `sig/` and us with an unreported bug.
@@ -79,6 +109,23 @@ module Rigor
         end
       end
 
+      # Issue #735 — unlike {#report_unrenderable} this is a fact about the PROJECT's type universe, not a
+      # Rigor defect: the class's superclass is not declared by any RBS the environment loads, so a sidecar
+      # declaring it would fail to build and take the class's type coverage with it. Naming the unresolved
+      # superclass is the actionable part — it is usually one gem's missing RBS standing between the user
+      # and signatures for a whole layer of their app.
+      def report_unresolvable_superclasses(unresolvable)
+        return if unresolvable.empty?
+
+        @err.puts(
+          "rigor sig-gen: skipped #{unresolvable.size} class(es) whose superclass no loaded RBS declares. " \
+          "A signature for them would fail to build (`RBS::NoSuperclassFoundError`) and would leave the " \
+          "class LESS typed than it is now. Provide RBS for the superclass — `rbs collection install`, the " \
+          "gem's own `sig/`, or a `signature_paths:` entry — and re-run."
+        )
+        unresolvable.sort.each { |class_name, superclass| @err.puts("  #{class_name} < #{superclass}") }
+      end
+
       def dispatch_print_or_diff(candidates, mode, options)
         SigGen::Renderer.new(out: @out).render(
           candidates: candidates,