rigortype 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1264f9aa0f9dfc20f74b28ee7302166c43e0b0c6ba7b30b0cf85b39b42020eb7
-  data.tar.gz: a324faeb0b6d0b2d87bfd2517c1712cd1511afcd2579d7659f4864a1a7451032
+  metadata.gz: 829d5d69b175d04f0f5a0e60d14d308b0df4ad4e11c96a8dd60fc34f3894a6a7
+  data.tar.gz: cd913caa8732865e82b463c5e1465b6a724f63e1eeb4023babbcd2b819911429
 SHA512:
-  metadata.gz: ca91af212669aa5f62e32c4475b907dd36b1d4dc425ff2ad48f39c1962919bc3e6a7a246eac4b7138bd318c00f9fa9b4f8054612b3b64dee86d8b83b58bbaf36
-  data.tar.gz: 462e42c61867f6b933d70590aeb4ee52476d8ae1f4e034727d0e4df5928cc4706a4634535813f757de1f5da01bf19ff64e09204d63a31c72c9382fe2be5a831d
+  metadata.gz: 8892ce6470ba6af8f9b1c30a2abb3911b622cb4ac5d68261cb20c0ba0859b2361536bec1add1ed42d4d61fd070394f0f5f51c2ac585c0c12323659e58caf3f45
+  data.tar.gz: 93eb3833381a707964a637277c5464f0ee1fb9cef75b39c995abff1eb42accfdc03ee8465b468f01497a9e1521ecfd6bb4faba7a21b8fb86492fba3a171536d2

data/lib/rigor/analysis/check_rules.rb

@@ -41,6 +41,28 @@ module Rigor
     # the first preview; later slices broaden it.
     # rubocop:disable Metrics/ModuleLength
     module CheckRules
+      # Stable identifiers for each rule. Used by the
+      # configuration `disable:` list and the in-source
+      # `# rigor:disable <rule>` suppression comment system
+      # to identify diagnostics by category. Rule identifiers
+      # are kebab-case strings; new rules MUST register here
+      # so user configuration can refer to them.
+      RULE_UNDEFINED_METHOD = "undefined-method"
+      RULE_WRONG_ARITY = "wrong-arity"
+      RULE_ARGUMENT_TYPE = "argument-type-mismatch"
+      RULE_NIL_RECEIVER = "possible-nil-receiver"
+      RULE_DUMP_TYPE = "dump-type"
+      RULE_ASSERT_TYPE = "assert-type"
+
+      ALL_RULES = [
+        RULE_UNDEFINED_METHOD,
+        RULE_WRONG_ARITY,
+        RULE_ARGUMENT_TYPE,
+        RULE_NIL_RECEIVER,
+        RULE_DUMP_TYPE,
+        RULE_ASSERT_TYPE
+      ].freeze
+
       module_function
 
       # Yields diagnostics for every unrecognised method call on
@@ -53,7 +75,7 @@ module Rigor
       # @param root [Prism::Node]
       # @param scope_index [Hash{Prism::Node => Rigor::Scope}]
       # @return [Array<Rigor::Analysis::Diagnostic>]
-      def diagnose(path:, root:, scope_index:) # rubocop:disable Metrics/CyclomaticComplexity
+      def diagnose(path:, root:, scope_index:, comments: [], disabled_rules: []) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         diagnostics = []
         Source::NodeWalker.each(root) do |node|
           next unless node.is_a?(Prism::CallNode)
@@ -64,6 +86,9 @@ module Rigor
           arity_diagnostic = wrong_arity_diagnostic(path, node, scope_index)
           diagnostics << arity_diagnostic if arity_diagnostic
 
+          arg_type_diagnostic = argument_type_diagnostic(path, node, scope_index)
+          diagnostics << arg_type_diagnostic if arg_type_diagnostic
+
           nil_diagnostic = nil_receiver_diagnostic(path, node, scope_index)
           diagnostics << nil_diagnostic if nil_diagnostic
 
@@ -73,7 +98,53 @@ module Rigor
           assert_diagnostic = assert_type_diagnostic(path, node, scope_index)
           diagnostics << assert_diagnostic if assert_diagnostic
         end
-        diagnostics
+        filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
+      end
+
+      # v0.0.2 #6 — diagnostic suppression. Two kinds of
+      # suppression compose:
+      #
+      # - **Project-level**: `disabled_rules` is the
+      #   project's `.rigor.yml` `disable:` list. Any
+      #   diagnostic whose `rule` is in the list is dropped.
+      # - **In-source**: `# rigor:disable <rule1>, <rule2>`
+      #   on the same line as the offending expression
+      #   suppresses the matching diagnostic for that line
+      #   only. `# rigor:disable all` on a line suppresses
+      #   every rule on that line.
+      #
+      # Diagnostics with `rule == nil` (parse errors, path
+      # errors, internal analyzer errors) are NEVER
+      # suppressed — they represent failures the user cannot
+      # silence away.
+      def filter_suppressed(diagnostics, comments:, disabled_rules:)
+        suppressions = parse_suppression_comments(comments)
+        disabled = disabled_rules.to_set(&:to_s)
+
+        diagnostics.reject do |diagnostic|
+          rule = diagnostic.rule
+          next false if rule.nil?
+          next true if disabled.include?(rule)
+
+          line_rules = suppressions[diagnostic.line]
+          line_rules && (line_rules.include?("all") || line_rules.include?(rule))
+        end
+      end
+
+      SUPPRESSION_PATTERN = /#\s*rigor:disable\s+(?<rules>[\w,\s-]+)/
+      private_constant :SUPPRESSION_PATTERN
+
+      def parse_suppression_comments(comments)
+        result = Hash.new { |h, k| h[k] = Set.new }
+        comments.each do |comment|
+          source = comment.location.slice
+          match = SUPPRESSION_PATTERN.match(source)
+          next if match.nil?
+
+          rules = match[:rules].to_s.split(/[\s,]+/).reject(&:empty?)
+          rules.each { |rule| result[comment.location.start_line] << rule }
+        end
+        result
       end
 
       # rubocop:disable Metrics/ClassLength
@@ -361,13 +432,14 @@ module Rigor
         # The diagnostic does NOT count toward `Result#error_count`
         # so a fixture peppered with `dump_type` calls still
         # passes `rigor check`.
-        def dump_type_diagnostic(path, call_node, scope_index)
+        def dump_type_diagnostic(path, call_node, scope_index) # rubocop:disable Metrics/CyclomaticComplexity
           return nil unless rigor_testing_call?(call_node, :dump_type)
           return nil if call_node.arguments.nil? || call_node.arguments.arguments.empty?
 
           arg = call_node.arguments.arguments.first
           scope = scope_index[arg] || scope_index[call_node]
           return nil if scope.nil?
+          return nil if inside_rigor_testing?(scope)
 
           type = scope.type_of(arg)
           location = call_node.message_loc || call_node.location
@@ -376,7 +448,8 @@ module Rigor
             line: location.start_line,
             column: location.start_column + 1,
             message: "dump_type: #{type.describe(:short)}",
-            severity: :info
+            severity: :info,
+            rule: RULE_DUMP_TYPE
           )
         end
 
@@ -388,7 +461,7 @@ module Rigor
         # is emitted; matching calls produce no output. This
         # lets a fixture document its expected types inline:
         # subsequent `rigor check` runs flag any drift.
-        def assert_type_diagnostic(path, call_node, scope_index) # rubocop:disable Metrics/CyclomaticComplexity
+        def assert_type_diagnostic(path, call_node, scope_index) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           return nil unless rigor_testing_call?(call_node, :assert_type)
           return nil if call_node.arguments.nil? || call_node.arguments.arguments.size < 2
 
@@ -398,6 +471,7 @@ module Rigor
           value_node = call_node.arguments.arguments[1]
           scope = scope_index[value_node] || scope_index[call_node]
           return nil if scope.nil?
+          return nil if inside_rigor_testing?(scope)
 
           actual = scope.type_of(value_node).describe(:short)
           expected = expected_node.unescaped.to_s
@@ -419,6 +493,24 @@ module Rigor
         RIGOR_TESTING_RECEIVERS = ["Rigor", "Rigor::Testing", "Testing"].freeze
         private_constant :RIGOR_TESTING_RECEIVERS
 
+        # The dump/assert helpers' own implementation methods
+        # call back into `Testing.dump_type` / `assert_type` to
+        # share the no-op runtime stub. We do NOT want those
+        # internal calls to surface diagnostics — they are
+        # reflexive plumbing, not user assertions. This filter
+        # skips diagnostics when the call site's `self_type` is
+        # the `Rigor` or `Rigor::Testing` module itself.
+        SELF_REFERENTIAL_SCOPES = ["Rigor", "Rigor::Testing"].freeze
+        private_constant :SELF_REFERENTIAL_SCOPES
+
+        def inside_rigor_testing?(scope)
+          self_type = scope.self_type
+          return false if self_type.nil?
+          return false unless self_type.respond_to?(:class_name)
+
+          SELF_REFERENTIAL_SCOPES.include?(self_type.class_name)
+        end
+
         def rigor_testing_call?(call_node, method_name)
           return false unless call_node.name == method_name
 
@@ -449,6 +541,7 @@ module Rigor
         def build_assert_type_diagnostic(path, call_node, expected, actual)
           location = call_node.message_loc || call_node.location
           Diagnostic.new(
+            rule: RULE_ASSERT_TYPE,
             path: path,
             line: location.start_line,
             column: location.start_column + 1,
@@ -460,6 +553,7 @@ module Rigor
         def build_nil_receiver_diagnostic(path, call_node)
           location = call_node.message_loc || call_node.location
           Diagnostic.new(
+            rule: RULE_NIL_RECEIVER,
             path: path,
             line: location.start_line,
             column: location.start_column + 1,
@@ -468,6 +562,117 @@ module Rigor
           )
         end
 
+        # v0.0.2 #4 — argument-type-mismatch diagnostic.
+        # Walks a call's positional arguments and checks each
+        # against the matching parameter's RBS type via
+        # `Rigor::Inference::Acceptance`. Emits an `:error`
+        # for the first argument whose type the parameter
+        # does NOT accept under the gradual mode.
+        #
+        # Conservative envelope (matches the wrong-arity rule
+        # plus a few additional skips):
+        # - Receiver must be Nominal / Singleton / Constant
+        #   (the same `concrete_class_name` test).
+        # - Method must be in RBS.
+        # - Method must have exactly ONE method type
+        #   (overload). Multi-overload checking is left for
+        #   a follow-up because picking the "intended"
+        #   overload requires the dispatcher's full
+        #   acceptance plumbing.
+        # - The selected overload must have NO
+        #   rest_positionals, NO required keywords, NO
+        #   trailing positionals.
+        # - The call must use plain positional arguments
+        #   (no splat / kw / block-pass / forwarded).
+        # - Per-argument: skip when EITHER side is `Dynamic`
+        #   (the call cannot be statically refuted).
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+        def argument_type_diagnostic(path, call_node, scope_index)
+          return nil if call_node.receiver.nil?
+          return nil unless plain_positional_call?(call_node)
+
+          scope = scope_index[call_node]
+          return nil if scope.nil?
+
+          receiver_type = scope.type_of(call_node.receiver)
+          class_name = concrete_class_name(receiver_type)
+          return nil if class_name.nil?
+
+          # NOTE: unlike the undefined-method / wrong-arity
+          # rules, we deliberately do NOT skip when
+          # `discovered_method?` matches. When the user
+          # supplies BOTH a `def` and an RBS sig, the sig is
+          # the authoritative parameter contract and we
+          # should validate calls against it.
+          loader = scope.environment.rbs_loader
+          return nil if loader.nil?
+          return nil unless loader.class_known?(class_name)
+          return nil unless definition_available?(loader, receiver_type, class_name)
+
+          method_def = lookup_method(loader, receiver_type, class_name, call_node.name)
+          return nil if method_def.nil? || method_def == true
+          return nil unless method_def.method_types.size == 1
+
+          mismatch = first_argument_mismatch(method_def.method_types.first, call_node, scope)
+          return nil if mismatch.nil?
+
+          build_argument_type_diagnostic(path, call_node, class_name, mismatch)
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+
+        def first_argument_mismatch(method_type, call_node, scope) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          function = method_type.type
+          return nil unless argument_check_eligible?(function)
+
+          params = function.required_positionals + function.optional_positionals
+          arguments = call_node.arguments&.arguments || []
+          arguments.each_with_index do |arg, index|
+            param = params[index]
+            next if param.nil? # arity mismatch is the wrong-arity rule's concern.
+
+            param_type = translate_param_type(param.type, scope.environment)
+            next if param_type.is_a?(Type::Dynamic) || param_type.is_a?(Type::Top)
+
+            arg_type = scope.type_of(arg)
+            next if arg_type.is_a?(Type::Dynamic) || arg_type.is_a?(Type::Top)
+
+            result = Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual)
+            return { node: arg, name: param.name, expected: param_type, actual: arg_type } if result.no?
+          end
+          nil
+        end
+
+        def argument_check_eligible?(function)
+          function.rest_positionals.nil? &&
+            function.required_keywords.empty? &&
+            function.optional_keywords.empty? &&
+            function.rest_keywords.nil? &&
+            function.trailing_positionals.empty?
+        end
+
+        def translate_param_type(rbs_type, _environment)
+          Inference::RbsTypeTranslator.translate(rbs_type)
+        rescue StandardError
+          Type::Combinator.untyped
+        end
+
+        def build_argument_type_diagnostic(path, call_node, class_name, mismatch)
+          location = mismatch[:node].location
+          method_label = "`#{call_node.name}' on #{class_name}"
+          parameter_label = mismatch[:name] ? "parameter `#{mismatch[:name]}' of #{method_label}" : method_label
+          message = "argument type mismatch at #{parameter_label}: " \
+                    "expected #{mismatch[:expected].describe(:short)}, " \
+                    "got #{mismatch[:actual].describe(:short)}"
+          Diagnostic.new(
+            rule: RULE_ARGUMENT_TYPE,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: message,
+            severity: :error
+          )
+        end
+
         # rubocop:disable Metrics/ParameterLists
         def build_arity_diagnostic(path, call_node, class_name, min, max, actual)
           location = call_node.message_loc || call_node.location
@@ -475,6 +680,7 @@ module Rigor
           method_label = "`#{call_node.name}' on #{class_name}"
           message = "wrong number of arguments to #{method_label} (given #{actual}, expected #{range})"
           Diagnostic.new(
+            rule: RULE_WRONG_ARITY,
             path: path,
             line: location.start_line,
             column: location.start_column + 1,
@@ -488,6 +694,7 @@ module Rigor
           location = call_node.message_loc || call_node.location
           rendered_receiver = receiver_type.describe
           Diagnostic.new(
+            rule: RULE_UNDEFINED_METHOD,
             path: path,
             line: location.start_line,
             column: location.start_column + 1,

data/lib/rigor/analysis/diagnostic.rb

@@ -3,14 +3,24 @@
 module Rigor
   module Analysis
     class Diagnostic
-      attr_reader :path, :line, :column, :message, :severity
+      attr_reader :path, :line, :column, :message, :severity, :rule
 
-      def initialize(path:, line:, column:, message:, severity: :error)
+      # `rule:` is the stable identifier (a kebab-case string)
+      # of the diagnostic's source rule. It is used by the
+      # configuration and the in-source `# rigor:disable <rule>`
+      # suppression comment system to identify diagnostics by
+      # category. Diagnostics not produced by `CheckRules`
+      # (parse errors, path errors, internal analyzer errors)
+      # may leave `rule` as nil and stay unsuppressible.
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(path:, line:, column:, message:, severity: :error, rule: nil)
+        # rubocop:enable Metrics/ParameterLists
         @path = path
         @line = line
         @column = column
         @message = message
         @severity = severity
+        @rule = rule
       end
 
       def error?
@@ -23,6 +33,7 @@ module Rigor
           "line" => line,
           "column" => column,
           "severity" => severity.to_s,
+          "rule" => rule,
           "message" => message
         }
       end

data/lib/rigor/analysis/runner.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../environment"
 require_relative "../scope"
+require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
 require_relative "check_rules"
 require_relative "diagnostic"
@@ -11,11 +12,12 @@ require_relative "result"
 
 module Rigor
   module Analysis
-    class Runner
+    class Runner # rubocop:disable Metrics/ClassLength
       RUBY_GLOB = "**/*.rb"
 
-      def initialize(configuration:)
+      def initialize(configuration:, explain: false)
         @configuration = configuration
+        @explain = explain
       end
 
       # Walks every Ruby file under `paths`, parses it, builds a
@@ -27,7 +29,10 @@ module Rigor
       # is built once at run start through `Environment.for_project`
       # so all files share the same RBS load.
       def run(paths = @configuration.paths)
-        environment = Environment.for_project
+        environment = Environment.for_project(
+          libraries: @configuration.libraries,
+          signature_paths: @configuration.signature_paths
+        )
         expansion = expand_paths(paths)
 
         diagnostics = expansion.fetch(:errors)
@@ -73,13 +78,20 @@ module Rigor
         )
       end
 
-      def analyze_file(path, environment)
+      def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
         parse_result = Prism.parse_file(path)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: environment)
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
-        CheckRules.diagnose(path: path, root: parse_result.value, scope_index: index)
+        diagnostics = CheckRules.diagnose(
+          path: path,
+          root: parse_result.value,
+          scope_index: index,
+          comments: parse_result.comments,
+          disabled_rules: @configuration.disabled_rules
+        )
+        diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [
           Diagnostic.new(
@@ -102,6 +114,37 @@ module Rigor
         ]
       end
 
+      # v0.0.2 #10 — fail-soft fallback explanation. When
+      # `--explain` is set the runner additionally walks the
+      # file with `Rigor::Inference::CoverageScanner` and emits
+      # one `:info` diagnostic per directly-unrecognized node,
+      # naming the node class and the type the engine fell back
+      # to. The CoverageScanner is the canonical "first-event-
+      # per-node" probe: it already filters out pass-through
+      # wrappers (`ProgramNode`, `StatementsNode`,
+      # `ParenthesesNode`) so the explain stream is attributable
+      # to the leaf node that actually triggered the fallback.
+      def explain_diagnostics(path, root, scope)
+        return [] unless @explain
+
+        result = Inference::CoverageScanner.new(scope: scope).scan(root)
+        result.events.map { |event| explain_diagnostic(path, event) }
+      end
+
+      def explain_diagnostic(path, event)
+        location = event.location
+        line = location ? location.start_line : 1
+        column = location ? location.start_column + 1 : 1
+        Diagnostic.new(
+          path: path,
+          line: line,
+          column: column,
+          message: "fail-soft fallback at #{event.node_class}: #{event.inner_type.describe(:short)}",
+          severity: :info,
+          rule: "fallback"
+        )
+      end
+
       def parse_diagnostics(path, parse_result)
         parse_result.errors.map do |error|
           location = error.location

data/lib/rigor/cli/type_of_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 require "prism"
 
+require_relative "../configuration"
 require_relative "../environment"
 require_relative "../scope"
 require_relative "../source/node_locator"
@@ -47,19 +48,20 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", trace: false }
+        options = { format: "text", trace: false, config: Configuration::DEFAULT_PATH }
 
         parser = OptionParser.new do |opts|
           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 }
         end
         parser.parse!(@argv)
 
         options
       end
 
-      def execute(target:, options:)
+      def execute(target:, options:) # rubocop:disable Metrics/AbcSize
         file, line, column = target
         return 1 unless file_exists?(file)
 
@@ -72,7 +74,8 @@ module Rigor
         return 1 if node.nil?
 
         tracer = options[:trace] ? Inference::FallbackTracer.new : nil
-        base_scope = Scope.empty(environment: project_environment(file))
+        configuration = Configuration.load(options.fetch(:config))
+        base_scope = Scope.empty(environment: project_environment(file, configuration))
 
         # Build a per-node scope index so locals bound earlier in the
         # file flow into the scope used to type the queried node. We
@@ -95,8 +98,11 @@ module Rigor
       # walk parent directories to find the enclosing `Gemfile`/`*.gemspec`
       # so probes against files outside the current process's CWD still
       # see the right `sig/` tree.
-      def project_environment(_file)
-        Environment.for_project
+      def project_environment(_file, configuration)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
       end
 
       def file_exists?(file)

data/lib/rigor/cli/type_scan_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 require "prism"
 
+require_relative "../configuration"
 require_relative "../environment"
 require_relative "../inference/coverage_scanner"
 require_relative "../scope"
@@ -44,11 +45,13 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", limit: 10, show_recognized: false, threshold: nil }
+        options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
+                    config: Configuration::DEFAULT_PATH }
 
         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 }
           opts.on("--limit=N", Integer, "Max example events to print (text only)") do |value|
             options[:limit] = value
           end
@@ -86,7 +89,8 @@ module Rigor
       end
 
       def scan_paths(paths, options)
-        scope = Scope.empty(environment: project_environment)
+        configuration = Configuration.load(options.fetch(:config))
+        scope = Scope.empty(environment: project_environment(configuration))
         scanner = Inference::CoverageScanner.new(scope: scope)
         accumulator = ScanAccumulator.new
         paths.each { |path| scan_one(path, scanner, accumulator) }
@@ -94,12 +98,13 @@ module Rigor
       end
 
       # Builds a project-aware environment that auto-detects `<cwd>/sig`
-      # so calls scoped to the current project resolve through the
-      # local RBS tree. Phase 2a does not yet wire stdlib opt-in here;
-      # that lands when the configuration layer (`.rigor.yml`) gains an
-      # `rbs:` section.
-      def project_environment
-        Environment.for_project
+      # by default and honours the configuration's `libraries:` /
+      # `signature_paths:` keys when present.
+      def project_environment(configuration)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
       end
 
       def scan_one(path, scanner, accumulator)

data/lib/rigor/cli.rb

@@ -68,19 +68,21 @@ module Rigor
 
       options = {
         config: Configuration::DEFAULT_PATH,
-        format: "text"
+        format: "text",
+        explain: false
       }
 
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: rigor check [options] [paths]"
         opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
         opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+        opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
       end
       parser.parse!(@argv)
 
       configuration = Configuration.load(options.fetch(:config))
       paths = @argv.empty? ? configuration.paths : @argv
-      result = Analysis::Runner.new(configuration: configuration).run(paths)
+      result = Analysis::Runner.new(configuration: configuration, explain: options.fetch(:explain)).run(paths)
 
       write_result(result, options.fetch(:format))
       result.success? ? 0 : 1
@@ -126,6 +128,23 @@ module Rigor
         #                `rigor type-scan` when no path is given.
         # - plugins:     reserved for future plugin contributions
         #                (no plugins are loaded today).
+        # - disable:     list of `rigor check` rule identifiers to
+        #                silence project-wide. The shipped rules are
+        #                undefined-method, wrong-arity,
+        #                argument-type-mismatch, possible-nil-receiver,
+        #                dump-type, assert-type. In-source
+        #                `# rigor:disable <rule>` comments at the end
+        #                of an offending line silence per-line; use
+        #                `# rigor:disable all` to suppress every rule.
+        # - libraries:   stdlib libraries to load on top of the
+        #                bundled defaults (e.g. ["csv", "set"]).
+        #                Each entry must be a name accepted by
+        #                `RBS::EnvironmentLoader#has_library?`.
+        # - signature_paths:
+        #                explicit list of `sig/`-style directories.
+        #                Leave unset (or `null`) to auto-detect
+        #                `<root>/sig`. Use `[]` to disable
+        #                project-RBS loading entirely.
         # - cache.path:  where Rigor will eventually persist
         #                analysis results across runs.
         #
@@ -167,15 +186,16 @@ module Rigor
     # the success and failure cases and reports the affected
     # file count for failures.
     def write_text_result(result)
+      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
+
       if result.success?
-        @out.puts("No diagnostics")
+        @out.puts("No diagnostics") if result.diagnostics.empty?
         return
       end
 
-      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
-      file_count = result.diagnostics.map(&:path).uniq.size
+      error_files = result.diagnostics.select(&:error?).map(&:path).uniq.size
       @out.puts("")
-      @out.puts("#{result.error_count} error(s) in #{file_count} file(s)")
+      @out.puts("#{result.error_count} error(s) in #{error_files} file(s)")
     end
 
     def help