rigortype 0.1.19 → 0.2.1

data/lib/rigor/cli/mutation_protection_renderer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renders a {MutationProtectionReport} (ADR-63 Tier 2) as text or JSON. The
+    # text form leads with the effectiveness ratio (caught breakages), then the
+    # breakages Rigor missed ("add a type here"), then the least-effective files.
+    # The framing is always *where to add a type*, never "your code is broken".
+    class MutationProtectionRenderer
+      TOP_CALLS = 15
+      TOP_FILES = 10
+
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(report, format:)
+        format == "json" ? render_json(report) : render_text(report)
+      end
+
+      private
+
+      def render_json(report)
+        @out.puts(JSON.pretty_generate(report.to_h))
+      end
+
+      def render_text(report)
+        pct = (report.ratio * 100).round(1)
+        @out.puts "Type-protection effectiveness (Tier 2 — mutation kill rate)"
+        @out.puts "  caught breakages: #{report.total_killed} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "  (effectiveness = when a type-visible bug was introduced, Rigor caught it)"
+        render_missed(report)
+        render_files(report)
+      end
+
+      def render_missed(report)
+        missed = report.missed
+        return if missed.empty?
+
+        @out.puts "\nAdd a type here — breakages Rigor missed (a wrong call that stayed silent):"
+        missed.first(TOP_CALLS).each do |call|
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
+                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+        end
+        @out.puts "  (#{missed.size - TOP_CALLS} more)" if missed.size > TOP_CALLS
+      end
+
+      def render_files(report)
+        worst = report.files.reject { |f| f.survived.zero? }.sort_by(&:ratio).first(TOP_FILES)
+        return if worst.empty?
+
+        @out.puts "\nLeast-effective files:"
+        worst.each do |file|
+          total = file.killed + file.survived
+          @out.puts format("  %<pct>5.1f%%  %<path>s  (%<n>d/%<total>d breakages caught)",
+                           pct: file.ratio * 100, path: file.path, n: file.killed, total: total)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/mutation_protection_report.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # ADR-63 Tier 2 — aggregates per-file {Protection::MutationScanner}
+    # results into a project-level *effectiveness* report: the kill ratio (when
+    # a type-visible bug was introduced, how often Rigor caught it), the per-file
+    # breakdown, and a ranked "add a type here" list keyed by the method whose
+    # breakage Rigor most often *missed* — the sites where a receiver annotation
+    # would buy real catching power.
+    #
+    # The framing is load-bearing (ADR-63 Criterion A / ADR-62 Criterion A): the
+    # number is *effectiveness*, the survivors are *missed breakages / where to
+    # add a type*, never "your code is broken".
+    FileEffectiveness = Data.define(:path, :killed, :survived, :ratio)
+    MissedBreakage = Data.define(:method_name, :count, :examples)
+
+    MutationProtectionReport = Data.define(:files, :missed, :parse_errors) do
+      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
+
+      def to_h
+        {
+          "mode" => "mutation",
+          "killed" => total_killed,
+          "survived" => total_survived,
+          "effectiveness_ratio" => ratio.round(4),
+          "files" => files.map do |f|
+            { "path" => f.path, "killed" => f.killed,
+              "survived" => f.survived, "ratio" => f.ratio.round(4) }
+          end,
+          "add_a_type_here" => missed.map do |m|
+            { "method" => m.method_name, "count" => m.count, "examples" => m.examples }
+          end,
+          "parse_errors" => parse_errors
+        }
+      end
+    end
+
+    class MutationProtectionAccumulator
+      def initialize
+        @files = []
+        @missed = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @parse_errors = []
+      end
+
+      def absorb(file_result)
+        @files << FileEffectiveness.new(
+          path: file_result.path, killed: file_result.killed,
+          survived: file_result.survived, ratio: file_result.ratio
+        )
+        file_result.sites.each do |site|
+          bucket = @missed[site.method_name]
+          bucket[:count] += 1
+          bucket[:examples] << "#{file_result.path}:#{site.line}" if bucket[:examples].size < 3
+        end
+      end
+
+      def record_parse_error(path, errors)
+        @parse_errors << { "path" => path, "errors" => errors.size }
+      end
+
+      def to_report
+        missed = @missed
+                 .map { |method, v| MissedBreakage.new(method_name: method, count: v[:count], examples: v[:examples]) }
+                 .sort_by { |m| [-m.count, m.method_name] }
+        MutationProtectionReport.new(files: @files, missed: missed, parse_errors: @parse_errors)
+      end
+    end
+  end
+end

data/lib/rigor/cli/options.rb

@@ -17,6 +17,15 @@ module Rigor
     module Options
       module_function
 
+      # Defines the standard `--config=PATH` flag on `parser`, writing the
+      # path into `options[:config]`. Used by every subcommand that loads a
+      # `.rigor.yml`; the few whose `--config` help text is intentionally
+      # bespoke (`diff`, `mcp`, `show-bleedingedge`) keep their own
+      # `parser.on` rather than this shared wording.
+      def add_config(parser, options)
+        parser.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+      end
+
       # Defines the `--tmp-file` / `--instead-of` editor-mode flag pair
       # on `parser`, writing into `options`.
       def add_editor_mode(parser, options)

data/lib/rigor/cli/plugins_command.rb

@@ -3,6 +3,7 @@
 require "optparse"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../plugin"
 require_relative "../plugin/loader"
 require_relative "../plugin/services"
@@ -102,7 +103,7 @@ module Rigor
         options = { config: nil, format: "text", strict: false, capabilities: false }
         OptionParser.new do |opts|
           opts.banner = USAGE
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
           opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
           opts.on("--capabilities", "Emit the per-plugin extension-protocol catalogue (ADR-37)") do

data/lib/rigor/cli/protection_renderer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text
+    # form leads with the protected ratio, then the highest-traffic untyped
+    # dispatches ("add a type here"), then the lowest-protected files. The
+    # framing is always *where to add a type*, never "your code is broken".
+    class ProtectionRenderer
+      TOP_CALLS = 15
+      TOP_FILES = 10
+
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(report, format:)
+        format == "json" ? render_json(report) : render_text(report)
+      end
+
+      private
+
+      def render_json(report)
+        @out.puts(JSON.pretty_generate(report.to_h))
+      end
+
+      def render_text(report)
+        pct = (report.ratio * 100).round(1)
+        @out.puts "Type-protection coverage (Tier 1 — dispatch-site receiver concreteness)"
+        @out.puts "  protected dispatch sites: #{report.total_protected} / #{report.grand_total}  (#{pct}%)"
+        @out.puts "  (protected = Rigor can catch a wrong call here; an upper bound on real protection)"
+        render_untyped_calls(report)
+        render_files(report)
+      end
+
+      def render_untyped_calls(report)
+        calls = report.untyped_calls
+        return if calls.empty?
+
+        @out.puts "\nAdd a type here — methods most often called on an untyped receiver:"
+        calls.first(TOP_CALLS).each do |call|
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
+                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+        end
+        @out.puts "  (#{calls.size - TOP_CALLS} more)" if calls.size > TOP_CALLS
+      end
+
+      def render_files(report)
+        worst = report.files.reject { |f| f.unprotected_count.zero? }.sort_by(&:ratio).first(TOP_FILES)
+        return if worst.empty?
+
+        @out.puts "\nLeast-protected files:"
+        worst.each do |file|
+          total = file.protected_count + file.unprotected_count
+          @out.puts format("  %<pct>5.1f%%  %<path>s  (%<n>d/%<total>d protected)",
+                           pct: file.ratio * 100, path: file.path, n: file.protected_count, total: total)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/protection_report.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner}
+    # results into a project-level protection report: the protected ratio, the
+    # per-file breakdown, and a ranked "add a type here" list keyed by the
+    # method called on an unprotected (`Dynamic`) receiver — the highest-traffic
+    # untyped dispatches, where a receiver annotation buys the most catching
+    # power.
+    FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio)
+    UntypedCall = Data.define(:method_name, :count, :examples)
+
+    ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors) do
+      def total_protected = files.sum(&:protected_count)
+      def total_unprotected = files.sum(&:unprotected_count)
+      def grand_total = total_protected + total_unprotected
+      def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
+
+      def to_h
+        {
+          "protected" => total_protected,
+          "unprotected" => total_unprotected,
+          "protection_ratio" => ratio.round(4),
+          "files" => files.map do |f|
+            { "path" => f.path, "protected" => f.protected_count,
+              "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4) }
+          end,
+          "add_a_type_here" => untyped_calls.map do |c|
+            { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+          end,
+          "parse_errors" => parse_errors
+        }
+      end
+    end
+
+    class ProtectionAccumulator
+      def initialize
+        @files = []
+        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @parse_errors = []
+      end
+
+      def absorb(path, file_result)
+        @files << FileProtection.new(
+          path: path, protected_count: file_result.protected_count,
+          unprotected_count: file_result.unprotected_count, ratio: file_result.ratio
+        )
+        file_result.sites.each do |site|
+          bucket = @calls[site.method_name]
+          bucket[:count] += 1
+          bucket[:examples] << "#{path}:#{site.line}" if bucket[:examples].size < 3
+        end
+      end
+
+      def record_parse_error(path, errors)
+        @parse_errors << { "path" => path, "errors" => errors.size }
+      end
+
+      def to_report
+        untyped = @calls
+                  .map { |method, v| UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples]) }
+                  .sort_by { |c| [-c.count, c.method_name] }
+        ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors)
+      end
+    end
+  end
+end

data/lib/rigor/cli/sig_gen_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../sig_gen"
 require_relative "command"
 
@@ -145,7 +146,7 @@ module Rigor
           opts.on("--tighter-returns", "Emit only tighter-return classifications") do
             options[:selection] << SigGen::Classification::TIGHTER_RETURN
           end
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
         end
       end
 

data/lib/rigor/cli/trace_command.rb

@@ -5,6 +5,7 @@ require "optionparser"
 require "prism"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../environment"
 require_relative "../scope"
 require_relative "../inference/flow_tracer"
@@ -63,7 +64,7 @@ module Rigor
             options[:line] = value
           end
           opts.on("--verbose", "Include every expression enter/result frame") { options[:verbose] = true }
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
         end
         parser.parse!(@argv)
         options

data/lib/rigor/cli/triage_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../analysis/runner"
 require_relative "../cache/store"
 require_relative "../triage"
@@ -42,7 +43,7 @@ module Rigor
         options = { config: nil, format: "text", top: 10, sections: DEFAULT_SECTIONS }
         OptionParser.new do |opts|
           opts.banner = USAGE
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          Options.add_config(opts, options)
           opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
           opts.on("--top=N", Integer, "Hotspot-file count (default 10)") { |v| options[:top] = v }
           opts.on("--hints-only", "Print only the heuristic-hints section") { options[:sections] = %i[hints] }

data/lib/rigor/cli/type_of_command.rb

@@ -53,7 +53,7 @@ module Rigor
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
           opts.on("--trace", "Record fail-soft fallbacks via FallbackTracer") { options[:trace] = true }
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
           Options.add_editor_mode(opts, options)
         end
         parser.parse!(@argv)

data/lib/rigor/cli/type_scan_command.rb

@@ -4,6 +4,7 @@ require "optionparser"
 require "prism"
 
 require_relative "../configuration"
+require_relative "options"
 require_relative "../environment"
 require_relative "../inference/coverage_scanner"
 require_relative "../scope"
@@ -46,7 +47,7 @@ module Rigor
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
-          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+          Options.add_config(opts, options)
           opts.on("--limit=N", Integer, "Max example events to print (text only)") do |value|
             options[:limit] = value
           end

data/lib/rigor/cli.rb

@@ -151,8 +151,9 @@ module Rigor
         # - target_ruby: minimum Ruby version your project targets.
         # - paths:       directories scanned by `rigor check` and
         #                `rigor type-scan` when no path is given.
-        # - plugins:     reserved for future plugin contributions
-        #                (no plugins are loaded today).
+        # - plugins:     opt-in list of plugin gem names to load.
+        #                See https://github.com/rigortype/rigor/tree/main/plugins
+        #                for production plugins (rigor-activerecord, rigor-sorbet, …).
         # - disable:     list of `rigor check` rule identifiers to
         #                silence project-wide. The shipped rules are
         #                call.undefined-method, call.wrong-arity,

data/lib/rigor/config_audit.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "signature_path_audit"
+require_relative "analysis/check_rules"
+
+module Rigor
+  # Audits a loaded {Configuration} for the class of mistake where a
+  # configured value silently resolves to nothing — a typo'd or moved
+  # path, an unknown library name, an inert rule id. The shared failure
+  # mode is that the loader filters the bad entry without a word, so the
+  # only symptom is downstream and confusing: missing signatures turn
+  # every call into the types they were meant to cover into a
+  # high-confidence `call.undefined-method`, and an unrecognised
+  # suppression token leaves the rule firing as if the `disable:` line
+  # were never written. This module surfaces each such entry up front so
+  # the cause is visible instead of inferred.
+  #
+  # Every check is held to the same bar that {SignaturePathAudit} set:
+  # it mirrors the loader's own acceptance test, so a warning means the
+  # loader really did load nothing, and it never fires on a setup that
+  # works. In particular the rule-token check only flags a token under a
+  # built-in family (`call`, `flow`, …) — a plugin- or `rbs_extended.*`
+  # rule id (whose family Rigor cannot statically enumerate, since a
+  # `node_rule` block emits any `rule:` string it likes) is left alone, so
+  # disabling a plugin rule is never mistaken for a typo.
+  module ConfigAudit
+    # One config-level finding. `kind` discriminates the source key
+    # (`:signature_path`, `:library`, `:disabled_rule`,
+    # `:severity_override`, `:bundler_bundle_path`, `:bundler_lockfile`,
+    # `:rbs_collection_lockfile`); `fields` carries the kind-specific
+    # structured data merged into {#to_h} for JSON consumers.
+    Warning = Data.define(:kind, :message, :fields) do
+      def to_h
+        { "kind" => kind.to_s, "message" => message }.merge(fields)
+      end
+    end
+
+    # @param configuration [Rigor::Configuration]
+    # @param project_root [String] the directory the run's relative
+    #   bundler / collection paths resolve against (the CLI's CWD), used
+    #   only by the explicit-path checks.
+    # @return [Array<Warning>]
+    def self.warnings(configuration, project_root: Dir.pwd)
+      signature_path_warnings(configuration) +
+        library_warnings(configuration) +
+        rule_token_warnings(configuration) +
+        explicit_path_warnings(configuration, project_root)
+    end
+
+    # `signature_paths:` entries that resolve to nothing — delegated to
+    # {SignaturePathAudit}, which mirrors the loader's `directory?` +
+    # recursive `**/*.rbs` acceptance test.
+    def self.signature_path_warnings(configuration)
+      SignaturePathAudit.warnings(configuration.signature_paths).map do |entry|
+        Warning.new(
+          kind: :signature_path,
+          message: entry.message,
+          fields: { "path" => entry.path, "status" => entry.status.to_s, "rbs_file_count" => entry.rbs_file_count }
+        )
+      end
+    end
+
+    # `libraries:` entries RBS does not recognise. Uses the same
+    # `RBS::EnvironmentLoader#has_library?` guard the loader filters
+    # through ({Environment::RbsLoader} `build_env_for`), so a flagged
+    # name is exactly one the loader skipped. Fails soft: if RBS itself
+    # raises, no warning rather than a crash.
+    def self.library_warnings(configuration)
+      configured = Array(configuration.libraries)
+      return [] if configured.empty?
+
+      loader = ::RBS::EnvironmentLoader.new
+      configured.reject { |lib| loader.has_library?(library: lib.to_s, version: nil) }.map do |lib|
+        Warning.new(
+          kind: :library,
+          message: "libraries: #{lib.to_s.inspect} is not an available RBS library (no signatures loaded from it)",
+          fields: { "name" => lib.to_s }
+        )
+      end
+    rescue StandardError
+      []
+    end
+
+    # `disable:` tokens and `severity_overrides:` keys that name no rule.
+    # Restricted to tokens under a built-in family so a plugin rule id is
+    # never mis-flagged (see the module docstring).
+    def self.rule_token_warnings(configuration)
+      disable = Array(configuration.disabled_rules).filter_map do |token|
+        next unless inert_builtin_token?(token.to_s)
+
+        Warning.new(
+          kind: :disabled_rule,
+          message: "disable: #{token.to_s.inspect} is not a recognized rule id; the suppression has no effect",
+          fields: { "token" => token.to_s }
+        )
+      end
+      overrides = configuration.severity_overrides.keys.filter_map do |key|
+        next unless inert_builtin_token?(key.to_s)
+
+        Warning.new(
+          kind: :severity_override,
+          message: "severity_overrides: #{key.to_s.inspect} is not a recognized rule id; the override has no effect",
+          fields: { "token" => key.to_s }
+        )
+      end
+      disable + overrides
+    end
+
+    # True when `token` looks like a built-in rule id but matches none —
+    # its first segment is a built-in family yet it is neither a bare
+    # family wildcard nor a known canonical id. A token whose family is
+    # not built-in (a plugin / `rbs_extended.*` rule, or a bare legacy
+    # alias) is deliberately NOT flagged: it may resolve at run time, so
+    # under-warning is the FP-safe choice.
+    def self.inert_builtin_token?(token)
+      family = token.split(".").first
+      return false unless Analysis::CheckRules::RULE_FAMILIES.include?(family)
+      return false if token == family
+      return false if Analysis::CheckRules::ALL_RULES.include?(token)
+
+      true
+    end
+
+    # Explicitly-configured bundler / rbs-collection paths that do not
+    # exist. Only the explicit form is audited (a nil value means
+    # auto-detection, which finding nothing is normal); messages stay
+    # factual about the path rather than guessing the fallback.
+    def self.explicit_path_warnings(configuration, project_root)
+      warnings = []
+      add_missing_dir(warnings, configuration.bundler_bundle_path, project_root,
+                      :bundler_bundle_path, "bundler.bundle_path")
+      add_missing_file(warnings, configuration.bundler_lockfile, project_root,
+                       :bundler_lockfile, "bundler.lockfile")
+      add_missing_file(warnings, configuration.rbs_collection_lockfile, project_root,
+                       :rbs_collection_lockfile, "rbs_collection.lockfile")
+      warnings
+    end
+
+    def self.add_missing_dir(warnings, path, project_root, kind, key)
+      return if path.nil? || File.directory?(File.expand_path(path, project_root))
+
+      warnings << Warning.new(kind: kind, message: "#{key}: #{path.inspect} is not a directory",
+                              fields: { "path" => path })
+    end
+
+    def self.add_missing_file(warnings, path, project_root, kind, key)
+      return if path.nil? || File.file?(File.expand_path(path, project_root))
+
+      warnings << Warning.new(kind: kind, message: "#{key}: #{path.inspect} does not exist", fields: { "path" => path })
+    end
+  end
+end

data/lib/rigor/configuration/dependencies.rb

@@ -9,10 +9,8 @@ module Rigor
     # inference instead of degrading to `Dynamic[top]` at the
     # dependency boundary.
     #
-    # Slice 1 lands the parser only — `Configuration#dependencies`
-    # is read, but no analyzer machinery consumes it yet. Slice 2
-    # wires `Analysis::DependencySourceInference` against this
-    # value object.
+    # Parser for the `dependencies:` YAML section; consumed by
+    # `Analysis::DependencySourceInference` (ADR-10).
     class Dependencies
       # Walking modes per
       # [ADR-10 § "Decision"](../../../docs/adr/10-dependency-source-inference.md#decision).