rigortype 0.3.5 → 0.3.7

data/lib/rigor/cli/effects_command.rb

@@ -3,7 +3,10 @@
 require "optionparser"
 
 require_relative "../configuration"
-require_relative "../analysis/runner"
+# ADR-104 — `analysis/runner` is required lazily (in `#analyze`), not here: a warm report served by
+# {Analysis::EffectsCacheProbe} must reach its answer without `rigor/inference` in `$LOADED_FEATURES`,
+# which is the whole of the boot saving. The probe pulls only the cache and the effects value layer.
+require_relative "../analysis/effects_cache_probe"
 require_relative "../effects/plugin_facts"
 require_relative "../effects/registry"
 require_relative "../plugin/loader"
@@ -94,7 +97,7 @@ module Rigor
         return list_labels(configuration) if options.fetch(:list_labels)
 
         scope = @argv.dup
-        table, sources = analyze(configuration, scope)
+        table, sources = resolve_table(configuration, scope)
         report = EffectsReport.build(
           table, full: options.fetch(:full), sources: sources, scope: scope,
                  label: options.fetch(:label), pure: options.fetch(:pure), limit: options.fetch(:limit)
@@ -231,6 +234,7 @@ module Rigor
       # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
       #   file each unit was defined in — the map {EffectsReport} needs to answer a path argument.
       def analyze(configuration, scope)
+        require_relative "../analysis/runner"
         runner = Analysis::Runner.new(
           configuration: configuration,
           cache_store: Cache::Store.new(root: configuration.cache_path),
@@ -240,6 +244,27 @@ module Rigor
         runner.run((configuration.paths + scope).uniq)
         [runner.effect_table, runner.effect_sources]
       end
+
+      # ADR-104 — the report before the engine. A warm run's whole answer is the #482 summary entry, so
+      # {Analysis::EffectsCacheProbe} tries to serve it without loading `rigor/inference`; any decline
+      # falls through to the full runner, which behaves exactly as it did.
+      #
+      # The report is a pure function of the table, the sources and the configuration: the envelope
+      # diagnostics the analysing path also computes are discarded here (this method reads the table
+      # and the sources and nothing else), which is what makes the served answer identical rather than
+      # merely similar.
+      def resolve_table(configuration, scope)
+        served = probe(configuration, scope)
+        return [served.table, served.sources] if served
+
+        analyze(configuration, scope)
+      end
+
+      def probe(configuration, scope)
+        Analysis::EffectsCacheProbe.new(
+          configuration: configuration, cache_root: configuration.cache_path
+        ).serve((configuration.paths + scope).uniq)
+      end
     end
   end
 end

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../effects/definition_lines"
+require_relative "../effects/snapshot"
 require_relative "../effects/snapshot_diff"
 require_relative "renderable"
 
@@ -16,8 +18,9 @@ module Rigor
     # the one line the whole workflow turns on: intent is expressed by regenerating and committing the
     # file, not by annotating the code.
     #
-    # It is deliberately not a diagnostic format: no severities, no positions, no exit-code weight of its
-    # own. The exit code comes from the gate.
+    # It is deliberately not a diagnostic format: no severities and no exit-code weight of its own — the
+    # exit code comes from the gate. A row carries a position for a reader to jump to, never one a
+    # `# rigor:disable` or a baseline could act on.
     class EffectsDiffRenderer
       include Renderable
 
@@ -41,9 +44,23 @@ module Rigor
       CLOSING_LINE = "Run `rigor effects explain` to see what caused this, and `rigor effects update` to " \
                      "accept it."
 
-      def initialize(out:, path:)
+      # A regeneration event routes to `update` alone: `explain` answers "what caused this label to
+      # appear", and the answer here is "the record was written under different rules", which explain
+      # cannot expand and the line above already said.
+      REGENERATION_CLOSING_LINE = "Run `rigor effects update` to regenerate the record under the current " \
+                                  "rules."
+
+      # @param sources [Hash{String=>Array<String>}] `Runner#effect_sources` — where each unit is defined.
+      #   A drift row names `file:line` so a reviewer does not have to search for the method (#435). The
+      #   file rides the cached summary entry and is free; the line is resolved by parsing the row's own
+      #   file ({Effects::DefinitionLines}), which is why a fresh report — no rows — still parses nothing
+      #   and the whole-project parse ADR-104 removed from this command stays removed.
+      # @param lines [Effects::DefinitionLines] seam for the specs; the default parses on demand.
+      def initialize(out:, path:, sources: nil, lines: Effects::DefinitionLines.new)
         @out = out
         @path = path
+        @sources = sources || {}
+        @lines = lines
       end
 
       private
@@ -67,10 +84,7 @@ module Rigor
 
         @out.puts("")
         @out.puts("#{section_name(table)}:")
-        events.each do |event|
-          suffix = qualified ? "  (#{event.table})" : ""
-          @out.puts("  #{render_event(event)}#{suffix}")
-        end
+        events.each { |event| @out.puts("  #{render_event(event, qualified: qualified)}") }
       end
 
       def section_name(table)
@@ -81,9 +95,38 @@ module Rigor
         end
       end
 
-      def render_event(event)
+      def render_event(event, qualified: false)
         marker = marker_for(event)
-        event.symbol.nil? ? marker : "#{event.symbol}  #{marker}"
+        return marker if event.symbol.nil?
+
+        "#{event.symbol}  #{marker}#{annotation(event, qualified)}"
+      end
+
+      # One parenthetical, never two: where the unit is defined, and — under `tolerated:`, which pools
+      # both tables — which table the event came from. A row with no known source under `tolerated:`
+      # renders exactly as it did before this suffix existed.
+      #
+      # A unit defined by a reopening spans several files and the row names them all rather than picking
+      # one; which of them a reviewer wants is exactly what the row cannot know.
+      def annotation(event, qualified)
+        parts = sources_of(event.symbol).map { |path, line| line ? "#{path}:#{line}" : path }
+        parts << event.table if qualified
+        parts.empty? ? "" : "  (#{parts.join(', ')})"
+      end
+
+      # Where a symbol is defined, as the two renderings share it — one implementation, so the text form
+      # and the JSON one cannot disagree about a position (WD3's rule).
+      #
+      # **A removed symbol has no entry here at all**, and cannot: `sources` is the CURRENT run's, and a
+      # method that no longer exists was not defined by it. Such a row renders exactly as it did before
+      # this suffix existed.
+      #
+      # @return [Array<Array(String, Integer)>] `[relative path, line]` per file, the line nil when that
+      #   file spells the key with no `def` — an accessor, or a definition the nesting cannot name.
+      def sources_of(symbol)
+        Array(@sources[symbol]).map do |path|
+          [Effects::Snapshot.relativize(path, Dir.pwd), @lines.for(key: symbol, path: path)]
+        end
       end
 
       def marker_for(event)
@@ -99,21 +142,48 @@ module Rigor
       def render_footer(diff)
         footer = diff.footer
         @out.puts("")
+        @out.puts(withheld_line(footer)) if diff.regeneration?
         unless footer[:added_symbols].zero? && footer[:removed_symbols].zero?
           @out.puts("symbols: +#{footer[:added_symbols]} / -#{footer[:removed_symbols]} " \
                     "(a rename is one of each)")
         end
-        @out.puts(CLOSING_LINE)
+        @out.puts(diff.regeneration? ? REGENERATION_CLOSING_LINE : CLOSING_LINE)
+      end
+
+      # What a regeneration withheld, said as a count. The counts below it are still printed, so the
+      # reader sees the scale of the difference without reading it row by row.
+      def withheld_line(footer)
+        suppressed = footer[:suppressed]
+        return "The two records are not comparable, so no per-method difference is shown." if
+          suppressed.zero?
+
+        noun = suppressed == 1 ? "1 per-method difference is" : "#{suppressed} per-method differences are"
+        "The two records were computed under different rules and are not comparable, so #{noun} not shown."
+      end
+
+      # The machine form carries the same position the text one prints (#435): a bot that annotates a pull
+      # request is the consumer with the most use for a line and the least ability to find one itself.
+      # `sources` is omitted rather than emitted empty when the row names nothing — a removed symbol.
+      def event_json(event)
+        row = event.to_h
+        sources = sources_of(event.symbol)
+        return row if sources.empty?
+
+        row.merge("sources" => sources.map do |path, line|
+          line ? { "path" => path, "line" => line } : { "path" => path }
+        end)
       end
 
       def render_json(diff)
         @out.puts(JSON.pretty_generate(
                     "fresh" => diff.fresh?,
-                    "events" => diff.events.map(&:to_h),
+                    "events" => diff.events.map { |event| event_json(event) },
                     "footer" => {
                       "added_symbols" => diff.footer[:added_symbols],
-                      "removed_symbols" => diff.footer[:removed_symbols]
+                      "removed_symbols" => diff.footer[:removed_symbols],
+                      "suppressed" => diff.footer[:suppressed]
                     },
+                    "regeneration" => diff.regeneration?,
                     "header" => {
                       "snapshot" => @path,
                       "gate" => diff.gate.to_s,

data/lib/rigor/cli/effects_explain_renderer.rb

@@ -22,8 +22,9 @@ module Rigor
     class EffectsExplainRenderer
       include Renderable
 
-      # One printed explanation. `path` is empty for a `methods:` row, whose explanation is the origin.
-      Row = Data.define(:table, :symbol, :label, :path, :origin)
+      # One printed explanation. `path` is empty for a `methods:` row, whose explanation is the origin;
+      # `causes` is non-empty only for an exhaustiveness row, which has neither (#435).
+      Row = Data.define(:table, :symbol, :label, :path, :origin, :causes)
 
       def initialize(out:)
         @out = out
@@ -44,6 +45,7 @@ module Rigor
       end
 
       def render_row(row)
+        return "#{row.symbol} stopped being exhaustive ← #{row.causes.join(', ')}" unless row.causes.empty?
         return "#{row.path.join(' → ')} [#{row.label}]" unless row.path.empty?
 
         origin = row.origin ? " ← #{row.origin}" : ""
@@ -58,7 +60,8 @@ module Rigor
                         "symbol" => row.symbol,
                         "label" => row.label,
                         "path" => row.path,
-                        "origin" => row.origin
+                        "origin" => row.origin,
+                        "causes" => row.causes
                       }
                     end
                   ))

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -3,7 +3,9 @@
 require "did_you_mean"
 require "optionparser"
 
-require_relative "../analysis/runner"
+# ADR-104 — `analysis/runner` is required lazily (in `#analyze`): a warm snapshot verb served by the
+# probe must reach its answer without `rigor/inference` in `$LOADED_FEATURES`.
+require_relative "../analysis/effects_cache_probe"
 require_relative "../cache/store"
 require_relative "../configuration"
 require_relative "../effects/discharge"
@@ -111,7 +113,8 @@ module Rigor
         )
         return explain(diff, options) if @verb == "explain"
 
-        EffectsDiffRenderer.new(out: @out, path: path).render(diff, format: options.fetch(:format))
+        EffectsDiffRenderer.new(out: @out, path: path, sources: @sources)
+                           .render(diff, format: options.fetch(:format))
         @verb == "check" && diff.drift? ? 1 : 0
       end
 
@@ -163,6 +166,9 @@ module Rigor
       # `methods:` change gets the origin in the method's own body.
       def rows_for_changes(diff)
         diff.events.flat_map do |event|
+          next exhaustiveness_rows(event) if
+            event.category == Effects::SnapshotDiff::EXHAUSTIVE_LOST
+
           labels = labels_of(event)
           next [] if labels.empty?
 
@@ -178,13 +184,29 @@ module Rigor
         entry ? entry.proven.to_a : []
       end
 
+      # `exhaustive → not` is the drift row a reader is least equipped to interpret, and it was the one
+      # row `explain` could not expand (#435): it carries no label, so {#labels_of} answered with nothing
+      # and the event produced no explanation at all. What explains it is the taint causes — the calls
+      # the analyzer could not follow — which is the detail the snapshot stopped recording per row
+      # (#434). The two halves meet here: the record keeps the stable count, and this names them.
+      def exhaustiveness_rows(event)
+        entry = @table[event.symbol]
+        return [] if entry.nil?
+
+        causes = Effects::Snapshot.render_causes(entry.causes)
+        return [] if causes.empty?
+
+        [EffectsExplainRenderer::Row.new(table: event.table, symbol: event.symbol, label: nil,
+                                         path: [].freeze, origin: nil, causes: causes)]
+      end
+
       def reach_rows(symbol, labels)
         labels.filter_map do |label|
           path = Effects::PathFinder.shortest(@table, symbol: symbol, label: label)
           next if path.nil?
 
           EffectsExplainRenderer::Row.new(table: "reach", symbol: symbol, label: label,
-                                          path: path.to_a, origin: path.origin)
+                                          path: path.to_a, origin: path.origin, causes: [].freeze)
         end
       end
 
@@ -197,7 +219,7 @@ module Rigor
           next if origin.nil?
 
           EffectsExplainRenderer::Row.new(table: "methods", symbol: symbol, label: label,
-                                          path: [].freeze, origin: origin.to_s)
+                                          path: [].freeze, origin: origin.to_s, causes: [].freeze)
         end
       end
 
@@ -207,7 +229,20 @@ module Rigor
       # the ADR-45 whole-run result cache like `rigor check` — the diagnostics entry plus the #382 effects
       # sidecar keyed beside it, so `rigor effects check` after `rigor check` under a configured `effects:`
       # block is a warm hit plus the fixpoint.
+      # ADR-104 — a snapshot is built from the table, the sources and the vocabulary, all three of which
+      # the #482 summary entry (plus the plugins' own declarations) carries, so a warm run takes the
+      # probe and never loads the engine. A decline is the runner path below, unchanged.
       def build_snapshot(configuration, full:)
+        served = Analysis::EffectsCacheProbe.new(
+          configuration: configuration, cache_root: configuration.cache_path
+        ).serve(configuration.paths)
+        return snapshot_from(configuration, full, served) if served
+
+        snapshot_from(configuration, full, analyze(configuration))
+      end
+
+      def analyze(configuration)
+        require_relative "../analysis/runner"
         runner = Analysis::Runner.new(
           configuration: configuration,
           cache_store: Cache::Store.new(root: configuration.cache_path),
@@ -215,14 +250,24 @@ module Rigor
           workers: 0
         )
         runner.run(configuration.paths)
-        @table = runner.effect_table
-        Effects::Snapshot.build(
-          table: @table, configuration: configuration, sources: runner.effect_sources, full: full,
+        Analysis::EffectsCacheProbe::Served.new(
+          table: runner.effect_table, sources: runner.effect_sources, plugin_facts: nil,
           registry: Effects::Registry.for_configuration(configuration,
                                                         plugin_facts: runner.effect_plugin_facts)
         )
       end
 
+      # WD3 — one build, whichever lane produced the inputs, so a served snapshot and an analysed one
+      # cannot drift in how they are assembled.
+      def snapshot_from(configuration, full, served)
+        @table = served.table
+        @sources = served.sources
+        Effects::Snapshot.build(
+          table: @table, configuration: configuration, sources: served.sources, full: full,
+          registry: served.registry
+        )
+      end
+
       # ---- options ------------------------------------------------
 
       def parse_options

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

@@ -55,6 +55,7 @@ module Rigor
                    0
                  end
         report_unrenderable(generator.unrenderable)
+        report_unresolvable_superclasses(generator.unresolvable_superclasses)
         status
       end
 
@@ -79,6 +80,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,