rigortype 0.3.7 → 0.3.9

data/lib/rigor/cli/doctor_command.rb

@@ -7,9 +7,11 @@ require_relative "../configuration"
 require_relative "../config_audit"
 require_relative "../analysis/baseline"
 require_relative "../analysis/result"
+require_relative "../environment/bundle_sig_discovery"
 require_relative "../plugin"
 require_relative "../plugin/loader"
 require_relative "../plugin/services"
+require_relative "../plugin_gap_advisory"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "check_invocation"
@@ -33,17 +35,12 @@ module Rigor
       CHECK_RBS = "rbs_environment"
       CHECK_PLUGINS = "plugins"
       CHECK_BASELINE = "baseline"
-      CHECK_RAILS = "rails_plugins"
+      CHECK_PLUGIN_GAP = "plugin_gap"
       CHECK_GEMFILE = "gemfile_install"
       CHECK_PLUGIN_SKEW = "plugin_skew"
+      CHECK_BUNDLE_LAYOUT = "bundle_layout"
 
-      RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
-      RAILS_PLUGIN_MARKERS = %w[
-        rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
-        rigor-rails-routes rigor-rails-i18n rigor-actioncable rigor-activestorage rigor-rails
-      ].freeze
-
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         configuration = Configuration.load(options.fetch(:config))
@@ -70,8 +67,8 @@ module Rigor
         # 5. Baseline drift check.
         findings.concat(check_baseline(configuration, result))
 
-        # 6. Rails locked but no Rails plugins.
-        findings.concat(check_rails_plugins(configuration))
+        # 6. Gems locked that a bundled plugin models, with that plugin not enabled (ADR-96 WD2).
+        findings.concat(check_plugin_gap(configuration))
 
         # 7. Rigor itself resolved as a project dependency.
         findings.concat(check_gemfile_install)
@@ -79,6 +76,9 @@ module Rigor
         # 8. A bundled plugin loaded from a different rigortype installation than the engine (#194 slice 3).
         findings.concat(check_plugin_skew(registry))
 
+        # 9. The project's gems are installed somewhere Rigor cannot see (ADR-25 carry-over).
+        findings.concat(check_bundle_layout(configuration))
+
         report(findings, options.fetch(:format))
         findings.any? { |f| f[:status] == :fail } ? 1 : 0
       rescue OptionParser::InvalidArgument => e
@@ -249,6 +249,46 @@ module Rigor
         File.expand_path(path)
       end
 
+      # ADR-25 carry-over — the plain `bundle install` layout. {Environment::BundleSigDiscovery} detects a
+      # bundle root only from paths the PROJECT records: `.bundle/config`'s `BUNDLE_PATH`, an in-tree
+      # `vendor/bundle`, or the user-global Bundler config. The default layout records none of those — the
+      # gems live in the active Ruby's `GEM_HOME`, which is a property of the project's toolchain, and
+      # ADR-27 keeps Rigor from running that toolchain to ask. So detection is not a bounded probe Rigor can
+      # add; what it CAN do is stop the state being silent. Without this the user sees gem-shipped `sig/`
+      # simply not taking effect, with nothing anywhere naming the reason.
+      #
+      # Warn, never fail: the layout is the Ruby default and is perfectly correct — only ~3% of gems ship
+      # `sig/` at all, so most projects lose nothing by it.
+      def check_bundle_layout(configuration)
+        return [] unless File.file?(File.join(Dir.pwd, "Gemfile.lock"))
+        return [] if resolved_bundle_root(configuration)
+
+        [
+          {
+            check: CHECK_BUNDLE_LAYOUT,
+            status: :warn,
+            message: "Gems are installed in the active Ruby's default gem home, which Rigor cannot locate — " \
+                     "no gem-shipped `sig/` is being discovered",
+            hint: "Rigor reads your project as data and never runs its toolchain, so it can only find a " \
+                  "bundle whose location the project records (`.bundle/config`'s `BUNDLE_PATH`, an in-tree " \
+                  "`vendor/bundle`, or your global Bundler config). Point it at the install root with " \
+                  "`bundler.bundle_path:` in `.rigor.yml`, run `bundle config set --local path vendor/bundle` " \
+                  "and reinstall, or supply signatures with `rbs collection install` instead."
+          }
+        ]
+      end
+
+      def resolved_bundle_root(configuration)
+        Environment::BundleSigDiscovery.resolve_bundle_path(
+          bundle_path: configuration.bundler_bundle_path,
+          project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect
+        )
+      rescue StandardError
+        # A doctor check must never be the thing that breaks the command it is diagnosing.
+        nil
+      end
+
       def check_baseline(configuration, result)
         path = configuration.baseline_path
         return [] if path.nil? || !File.exist?(path)
@@ -287,38 +327,45 @@ module Rigor
         parts.join(", ")
       end
 
-      def check_rails_plugins(configuration)
-        return [] unless rails_unconfigured?(configuration)
-
-        [
-          {
-            check: CHECK_RAILS,
-            status: :fail,
-            message: "Rails detected but no Rails plugins enabled",
-            hint: "Add Rails plugins (e.g. rigor-activerecord, rigor-actionpack) to " \
-                  "`.rigor.yml` `plugins:` so framework calls resolve."
-          }
-        ]
+      # ADR-96 WD2 — the plugin-gap advisory, read off each bundled plugin's `target_gems:` rather than the
+      # Rails-only tables it replaces. Per plugin, so a Rails app that enabled only `rigor-activerecord` now
+      # hears about the other seven; `:warn`, because declining a plugin is a legitimate choice and must not
+      # fail the command forever. The one `:fail` is today's behaviour generalised: the project depends on
+      # gems Rigor models and enables none of the plugins that model them, which is genuinely unconfigured.
+      # Both branches read the lockfile's `DEPENDENCIES` section, never its resolved graph: a transitive
+      # `minitest` or `i18n` rides along in nearly every Rails lock, and failing `doctor` on one would fail a
+      # correctly configured project.
+      def check_plugin_gap(configuration)
+        return [] if Configuration.discover.nil?
+
+        gaps = PluginGapAdvisory.gaps(project_root: Dir.pwd, plugins: configuration.plugins)
+        return [] if gaps.empty?
+
+        if PluginGapAdvisory.unconfigured?(project_root: Dir.pwd, plugins: configuration.plugins)
+          [unconfigured_plugin_finding(gaps)]
+        else
+          gaps.map { |gap| plugin_gap_finding(gap) }
+        end
       end
 
-      # True when Rails is in Gemfile.lock but the config enables no Rails plugin — the same probe {ProjectStateProbe}
-      # uses.
-      def rails_unconfigured?(_configuration)
-        config_path = Configuration.discover
-        return false if config_path.nil?
-        return false unless File.file?(config_path)
-
-        lock = File.join(Dir.pwd, "Gemfile.lock")
-        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
-
-        !file_mentions_any?(config_path, RAILS_PLUGIN_MARKERS)
+      def unconfigured_plugin_finding(gaps)
+        {
+          check: CHECK_PLUGIN_GAP,
+          status: :fail,
+          message: "#{gaps.size} bundled plugin(s) model gems this project depends on and none is enabled " \
+                   "(#{gaps.map(&:plugin_gem).join(', ')})",
+          hint: "Add the plugins for your stack to `.rigor.yml` `plugins:` so framework calls resolve."
+        }
       end
 
-      def file_mentions_any?(path, markers)
-        content = File.read(path)
-        markers.any? { |marker| content.include?(marker) }
-      rescue StandardError
-        false
+      def plugin_gap_finding(gap)
+        {
+          check: CHECK_PLUGIN_GAP,
+          status: :warn,
+          message: "#{gap.locked_gems.join(', ')} #{gap.locked_gems.one? ? 'is a dependency' : 'are dependencies'} " \
+                   "of this project and #{gap.plugin_gem} models it, but it is not enabled",
+          hint: "Add `#{gap.plugin_gem}` to `.rigor.yml` `plugins:`, or leave it out deliberately."
+        }
       end
 
       # Rigor is a tool, not a library (ADR-27): resolving it as one of the project's own dependencies pins the

data/lib/rigor/cli/effects_command.rb

@@ -41,7 +41,7 @@ module Rigor
     class EffectsCommand < Command
       USAGE = "Usage: rigor effects [options] [paths]"
 
-      # @return [Integer] CLI exit status: 0 on success, 1 on `check` drift, 64 on a usage error.
+      # @return CLI exit status: 0 on success, 1 on `check` drift, 64 on a usage error.
       def run
         verb = @argv.first
         return run_verb(verb) if EffectsSnapshotCommand::VERBS.include?(verb)
@@ -231,7 +231,7 @@ module Rigor
       # project does — still analyses it. Inside a project the argument is already under `paths:` and the
       # union is the configured set unchanged.
       #
-      # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
+      # @return 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"

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -50,12 +50,12 @@ module Rigor
       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.
+      # @param sources — `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.
+      # @param lines — seam for the specs; the default parses on demand.
       def initialize(out:, path:, sources: nil, lines: Effects::DefinitionLines.new)
         @out = out
         @path = path
@@ -121,7 +121,7 @@ module Rigor
       # 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
+      # @return `[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|

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -51,7 +51,7 @@ module Rigor
         @verb = verb
       end
 
-      # @return [Integer] 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
+      # @return 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
       def run
         options = parse_options
         return usage_error("unsupported format: #{options.fetch(:format)}") unless

data/lib/rigor/cli/explain_command.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "../analysis/rule_catalog"
+require_relative "../sig_gen/skip_reason_catalog"
 require_relative "command"
 
 module Rigor
@@ -18,7 +19,7 @@ module Rigor
     class ExplainCommand < Command
       USAGE = "Usage: rigor explain [options] [<rule>]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
 
@@ -28,6 +29,12 @@ module Rigor
         end
 
         token = @argv.shift
+        skip_reason = SigGen::SkipReasonCatalog.resolve(token)
+        if skip_reason
+          render_skip_reason(skip_reason, options.fetch(:format))
+          return 0
+        end
+
         entries = Analysis::RuleCatalog.resolve(token)
         if entries.empty?
           @err.puts("Unknown rule: #{token}")
@@ -68,6 +75,32 @@ module Rigor
         @out.puts("")
         @out.puts("Run `rigor explain <rule>` for the full description.")
         @out.puts("Family wildcards (`call`, `flow`, `assert`, `dump`, `def`) print every rule under that prefix.")
+        @out.puts("")
+        @out.puts("`rigor sig-gen` skip reasons:")
+        @out.puts("")
+        SigGen::SkipReasonCatalog.all.each do |entry|
+          @out.puts("  #{entry.id.ljust(33)} #{entry.summary}")
+        end
+      end
+
+      def render_skip_reason(entry, format)
+        if format == "json"
+          @out.puts(JSON.pretty_generate(entry.to_h))
+          return
+        end
+
+        @out.puts(entry.id)
+        @out.puts("=" * entry.id.length)
+        @out.puts("")
+        @out.puts(entry.summary)
+        @out.puts("")
+        @out.puts("A `rigor sig-gen` skip reason, not a diagnostic rule: it reports a signature that was NOT")
+        @out.puts("written, so it has no severity and nothing to suppress.")
+        @out.puts("")
+        @out.puts(entry.explanation)
+        @out.puts("")
+        @out.puts("What to do:")
+        @out.puts("  #{entry.next_step}")
       end
 
       def render_entries(entries, format)

data/lib/rigor/cli/fused_protection_report.rb

@@ -12,7 +12,13 @@ module Rigor
     # Framing (ADR-63 / ADR-62 Criterion A, extended): the payload is the **attribution** — which protection axis is
     # missing — never raw survival. An unprotected site is "add protection here", never "your code is broken".
     # `harness_errors` (#264) — see {Rigor::CLI::FileEffectiveness}; defaults to 0 for the same reason.
-    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio, :harness_errors) do
+    # A `class ... < Data.define(...)` body, not the `Data.define(...) do ... end` shorthand: Steep
+    # resolves a `def` inside the shorthand block against the *lexically enclosing* class (here,
+    # `Rigor::CLI`, which declares its own differently-shaped `initialize`) rather than the anonymous
+    # Data subclass being defined — a `sig/` declaration for `FusedFileProtection` cannot fix this,
+    # since the misattribution happens before any signature is consulted. The explicit `class` keyword
+    # is a real namespace boundary Steep's block walker respects; behaviour is identical either way.
+    class FusedFileProtection < Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio, :harness_errors)
       def initialize(path:, type_killed:, test_killed:, unprotected:, ratio:, harness_errors: 0)
         super
       end

data/lib/rigor/cli/lsp_command.rb

@@ -15,7 +15,7 @@ module Rigor
     class LspCommand < Command
       USAGE = "Usage: rigor lsp [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options == :usage_error

data/lib/rigor/cli/mcp_command.rb

@@ -17,7 +17,7 @@ module Rigor
     class McpCommand < Command
       USAGE = "Usage: rigor mcp [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options == :usage_error

data/lib/rigor/cli/measurement_integrity_warning.rb

@@ -20,15 +20,14 @@ module Rigor
     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]
+      # @param report — both expose the two counts.
+      # @param err — the stream to warn on.
+      # @param floor — {CoverageMutation::HARNESS_ERROR_WARN_FLOOR}.
       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.
+      # @return 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

data/lib/rigor/cli/mutation_fork_scan.rb

@@ -32,12 +32,12 @@ module Rigor
       # reliably marshalable, and the accumulator only needs the count).
       ParseError = Data.define(:count)
 
-      # @param paths [Array<String>] the files to measure, in caller order.
-      # @param scanner [Protection::MutationScanner] built on the parent; COW-inherited by workers.
-      # @param environment [Rigor::Environment] the scanner's environment, prewarmed here before forking.
-      # @param configuration [Rigor::Configuration] for the Prism `target_ruby` version.
-      # @param workers [Integer] resolved worker count (≤1 → sequential).
-      # @return [Hash{String => Protection::MutationScanner::FileResult, ParseError}] one entry per path.
+      # @param paths — the files to measure, in caller order.
+      # @param scanner — built on the parent; COW-inherited by workers.
+      # @param environment — the scanner's environment, prewarmed here before forking.
+      # @param configuration — for the Prism `target_ruby` version.
+      # @param workers — resolved worker count (≤1 → sequential).
+      # @return one entry per path.
       def run(paths:, scanner:, environment:, configuration:, workers:)
         # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
         # than each rebuilding it after the fork. A no-op on the sequential path but cheap.

data/lib/rigor/cli/mutation_protection_report.rb

@@ -14,7 +14,13 @@ module Rigor
     # `harness_errors` (#264) — mutants where the harness itself raised (a rescued failure), distinguished from
     # a parse-invalid mutant. Defaults to 0 so existing call sites keep constructing a `FileEffectiveness`
     # without the new keyword.
-    FileEffectiveness = Data.define(:path, :killed, :survived, :ratio, :harness_errors) do
+    # A `class ... < Data.define(...)` body, not the `Data.define(...) do ... end` shorthand: Steep
+    # resolves a `def` inside the shorthand block against the *lexically enclosing* class (here,
+    # `Rigor::CLI`, which declares its own differently-shaped `initialize`) rather than the anonymous
+    # Data subclass being defined — a `sig/` declaration for `FileEffectiveness` cannot fix this,
+    # since the misattribution happens before any signature is consulted. The explicit `class` keyword
+    # is a real namespace boundary Steep's block walker respects; behaviour is identical either way.
+    class FileEffectiveness < Data.define(:path, :killed, :survived, :ratio, :harness_errors)
       def initialize(path:, killed:, survived:, ratio:, harness_errors: 0)
         super
       end

data/lib/rigor/cli/plugin_command.rb

@@ -64,7 +64,7 @@ module Rigor
       PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
       EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         subcommand = @argv.shift || "list"
 

data/lib/rigor/cli/plugins_command.rb

@@ -62,7 +62,7 @@ module Rigor
     class PluginsCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor plugins [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         config_path = options.fetch(:config) || Configuration.discover
@@ -143,6 +143,7 @@ module Rigor
         required_by = loaded_ids & Plugin::Inflector::CONSUMER_PLUGIN_IDS
         return nil if required_by.empty?
 
+        Plugin::Isolation.configured_strategy = configuration.plugins_isolation
         Plugin::Isolation.target_bundle_root ||= Environment::BundleSigDiscovery.resolve_bundle_path(
           bundle_path: configuration.bundler_bundle_path,
           project_root: Dir.pwd,

data/lib/rigor/cli/prism_colorizer.rb

@@ -35,8 +35,8 @@ module Rigor
 
       VARIABLE_TOKENS = %i[INSTANCE_VARIABLE CLASS_VARIABLE GLOBAL_VARIABLE].freeze
 
-      # @param source [String] Ruby source.
-      # @return [String] the source with ANSI colour escapes, or
+      # @param source — Ruby source.
+      # @return the source with ANSI colour escapes, or
       #   the input unchanged when lexing surfaces an error.
       def colorize(source)
         # Sources read under a POSIX locale arrive tagged US-ASCII even when they carry UTF-8 bytes; retag so the token

data/lib/rigor/cli/protection_fork_scan.rb

@@ -23,12 +23,12 @@ module Rigor
       # reliably marshalable, and the accumulator only needs the count).
       ParseError = Data.define(:count)
 
-      # @param paths [Array<String>] the files to scan, in caller order.
-      # @param scanner [Inference::ProtectionScanner] built on the parent; COW-inherited by workers.
-      # @param environment [Rigor::Environment] the scanner's environment, prewarmed here before forking.
-      # @param configuration [Rigor::Configuration] for the Prism `target_ruby` version.
-      # @param workers [Integer] resolved worker count (≤1 → sequential).
-      # @return [Hash{String => Inference::ProtectionScanner::FileResult, ParseError}] one entry per path.
+      # @param paths — the files to scan, in caller order.
+      # @param scanner — built on the parent; COW-inherited by workers.
+      # @param environment — the scanner's environment, prewarmed here before forking.
+      # @param configuration — for the Prism `target_ruby` version.
+      # @param workers — resolved worker count (≤1 → sequential).
+      # @return one entry per path.
       def run(paths:, scanner:, environment:, configuration:, workers:)
         # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
         # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm). A

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -21,7 +21,7 @@ module Rigor
     class ShowBleedingedgeCommand < Command
       USAGE = "Usage: rigor show-bleedingedge [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         configuration = load_configuration(options)

data/lib/rigor/cli/sig_gen_command.rb

@@ -33,7 +33,13 @@ module Rigor
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
-      # @return [Integer] CLI exit status.
+      # 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 CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options.nil?
@@ -54,6 +60,7 @@ 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
@@ -61,6 +68,28 @@ module Rigor
 
       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.
@@ -106,7 +135,7 @@ module Rigor
         )
       end
 
-      # @return [Integer] exit status — non-zero when a file the user asked to write could not be written.
+      # @return exit status — non-zero when a file the user asked to write could not be written.
       def dispatch_write(candidates, configuration, options)
         layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
         path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)

data/lib/rigor/cli/skill_command.rb

@@ -76,7 +76,7 @@ module Rigor
       # up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         case @argv.first
         when nil

data/lib/rigor/cli/skill_deep_probe.rb

@@ -37,22 +37,22 @@ module Rigor
       #   that could not run is NOT a clean check and the report must never let it read as one.
       # - `route` / `reason` — the headline override, or nil to leave the presence-only recommendation standing.
       Report = Data.define(:status, :detail, :route, :reason) do
-        # @return [Boolean] true when the check did not complete — the caller must then say so rather than let the
+        # @return true when the check did not complete — the caller must then say so rather than let the
         #   fallback recommendation read as an all-clear.
         def failed?
           status == :error
         end
       end
 
-      # @param config [String, nil] the config filename the presence probe found, relative to `root`.
-      # @param root [String] project root (the analysis itself resolves paths against the process cwd, as
+      # @param config — the config filename the presence probe found, relative to `root`.
+      # @param root — project root (the analysis itself resolves paths against the process cwd, as
       #   `rigor check` does).
       def initialize(config:, root: Dir.pwd)
         @config = config
         @root = root
       end
 
-      # @return [Report] never raises — every failure degrades to a `:error`/`:skipped` report whose `route` is nil,
+      # @return never raises — every failure degrades to a `:error`/`:skipped` report whose `route` is nil,
       #   leaving the presence-only headline in charge.
       def run
         if @config.nil?