rigortype 0.2.4 → 0.2.6

data/lib/rigor/cli/doctor_command.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../config_audit"
+require_relative "../analysis/baseline"
+require_relative "../analysis/result"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+require_relative "check_runner_factory"
+require_relative "command"
+require_relative "options"
+
+module Rigor
+  class CLI
+    # `rigor doctor` — classify existing project findings into setup-problem
+    # vs clean-run with a routed next action (ADR-77 WD1).
+    #
+    # It is a presentation/aggregation layer over data `rigor check` already
+    # produces — no new analysis pass and no new diagnostic rule.  The
+    # command runs a scoped analysis to gather stats, audits the
+    # configuration, validates plugins, and checks baseline drift, then
+    # reports a small fixed set of checks with a hint for each failure.
+    class DoctorCommand < Command # rubocop:disable Metrics/ClassLength
+      USAGE = "Usage: rigor doctor [options]"
+
+      # Check identifiers — the stable JSON contract (`checks[].id`).
+      CHECK_CONFIG = "config_audit"
+      CHECK_RBS = "rbs_environment"
+      CHECK_PLUGINS = "plugins"
+      CHECK_BASELINE = "baseline"
+      CHECK_RAILS = "rails_plugins"
+
+      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.
+      def run
+        options = parse_options
+        configuration = Configuration.load(options.fetch(:config))
+        findings = []
+
+        # 1. Config audit (cheap — no analysis needed).
+        findings.concat(audit_config(configuration))
+
+        # 2. Run a scoped analysis to gather stats + diagnostics for the
+        #    deeper checks.  Use no-cache so the probe doesn't churn disk.
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: { no_cache: true, explain: false, stats: true, workers: 0 },
+          buffer: nil,
+          cache_root: configuration.cache_path
+        )
+        result = runner.run(configuration.paths)
+
+        # 3. RBS environment check.
+        findings.concat(check_rbs_environment(result))
+
+        # 4. Plugin load check.
+        findings.concat(check_plugins(configuration))
+
+        # 5. Baseline drift check.
+        findings.concat(check_baseline(configuration, result))
+
+        # 6. Rails locked but no Rails plugins.
+        findings.concat(check_rails_plugins(configuration))
+
+        report(findings, options.fetch(:format))
+        findings.any? { |f| f[:status] == :fail } ? 1 : 0
+      rescue OptionParser::InvalidArgument => e
+        @err.puts(e.message)
+        CLI::EXIT_USAGE
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text" }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
+        end.parse!(@argv)
+        validate!(options)
+        options
+      end
+
+      def validate!(options)
+        return if %w[text json].include?(options.fetch(:format))
+
+        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      end
+
+      # ------------------------------------------------------------------
+      # Individual checks — each returns an Array of finding Hashes.
+      # A finding has: :check, :status (:pass/:fail/:warn), :message, :hint
+      # ------------------------------------------------------------------
+
+      def audit_config(configuration)
+        warnings = ConfigAudit.warnings(configuration, project_root: Dir.pwd)
+        return [] if warnings.empty?
+
+        messages = warnings.map(&:message)
+        [
+          {
+            check: CHECK_CONFIG,
+            status: :fail,
+            message: "Configuration warnings: #{messages.size}",
+            hint: "Review and fix the flagged entries in your config file."
+          }
+        ]
+      end
+
+      def check_rbs_environment(result)
+        stats = result.stats
+        return [] unless stats
+
+        if stats.rbs_classes_total.zero?
+          [
+            {
+              check: CHECK_RBS,
+              status: :fail,
+              message: "RBS environment is empty (#{stats.rbs_classes_total} classes available)",
+              hint: "The RBS environment failed to build or loaded no signatures. " \
+                    "Check `signature_paths:` for duplicate declarations, or run " \
+                    "`rbs collection install` for gem signatures."
+            }
+          ]
+        else
+          [
+            {
+              check: CHECK_RBS,
+              status: :pass,
+              message: "RBS environment healthy (#{stats.rbs_classes_total} classes available)",
+              hint: nil
+            }
+          ]
+        end
+      end
+
+      def check_plugins(configuration)
+        services = Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: nil
+        )
+        registry = Plugin::Loader.load(configuration: configuration, services: services)
+        errors = registry.load_errors
+        return [] if errors.empty?
+
+        [
+          {
+            check: CHECK_PLUGINS,
+            status: :fail,
+            message: "Plugin load errors: #{errors.size}",
+            hint: "Run `rigor plugins --strict` for the full per-plugin report."
+          }
+        ]
+      end
+
+      def check_baseline(configuration, result)
+        path = configuration.baseline_path
+        return [] if path.nil? || !File.exist?(path)
+
+        baseline = Analysis::Baseline.load(path, project_root: Dir.pwd)
+        return [] if baseline.nil? || baseline.empty?
+
+        drifted = baseline.audit(result.diagnostics).reject { |row| row.status == :within }
+        return [] if drifted.empty?
+
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :fail,
+            message: "Baseline drift detected (#{baseline_drift_summary(drifted)})",
+            hint: "Run `rigor baseline regenerate` to refresh the baseline."
+          }
+        ]
+      rescue Analysis::Baseline::LoadError, Psych::SyntaxError => e
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :warn,
+            message: "Baseline load failed: #{e.message}",
+            hint: "Check the baseline file path in your config."
+          }
+        ]
+      end
+
+      def baseline_drift_summary(drifted)
+        counts = drifted.group_by(&:status).transform_values(&:size)
+        parts = []
+        parts << "#{counts.fetch(:over, 0)} over threshold" if counts.key?(:over)
+        parts << "#{counts.fetch(:cleared, 0)} cleared" if counts.key?(:cleared)
+        parts << "#{counts.fetch(:reducible, 0)} reducible" if counts.key?(:reducible)
+        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."
+          }
+        ]
+      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)
+      end
+
+      def file_mentions_any?(path, markers)
+        content = File.read(path)
+        markers.any? { |marker| content.include?(marker) }
+      rescue StandardError
+        false
+      end
+
+      # ------------------------------------------------------------------
+      # Reporting
+      # ------------------------------------------------------------------
+
+      def report(findings, format)
+        case format
+        when "json" then report_json(findings)
+        else report_text(findings)
+        end
+      end
+
+      def report_json(findings)
+        payload = {
+          "status" => findings.any? { |f| f[:status] == :fail } ? "issues_found" : "clean",
+          "checks" => findings.map do |f|
+            {
+              "id" => f[:check].to_s,
+              "status" => f[:status].to_s,
+              "message" => f[:message],
+              "hint" => f[:hint]
+            }
+          end
+        }
+        @out.puts(JSON.pretty_generate(payload))
+      end
+
+      def report_text(findings)
+        failures = findings.select { |f| f[:status] == :fail }
+        warnings = findings.select { |f| f[:status] == :warn }
+        passes = findings.select { |f| f[:status] == :pass }
+
+        if failures.empty? && warnings.empty?
+          @out.puts("rigor doctor: all checks passed — no setup problems detected.")
+        else
+          @out.puts("rigor doctor: #{failures.size} issue(s) found")
+          failures.each { |f| print_finding(f) }
+          warnings.each { |f| print_finding(f) } unless warnings.empty?
+        end
+
+        passes.each { |f| print_finding(f) } unless passes.empty?
+      end
+
+      def print_finding(finding)
+        label = case finding[:status]
+                when :fail then "[FAIL]"
+                when :warn then "[WARN]"
+                else "[PASS]"
+                end
+        @out.puts("#{label} #{finding[:check]}: #{finding[:message]}")
+        @out.puts("  → #{finding[:hint]}") if finding[:hint]
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugins_command.rb

@@ -37,7 +37,7 @@ module Rigor
     #   `source_rbs_synthesizer:`);
     # - the ADR-37 narrow extension protocols read off the plugin
     #   class — `node_rule` node types, `dynamic_return` receivers,
-    #   `type_specifier` methods.
+    #   `narrowing_facts` methods.
     #
     # `--capabilities` switches to a focused catalogue of just the
     # narrow-protocol gate values + produced/consumed facts (ADR-37
@@ -194,7 +194,7 @@ module Rigor
 
       # ADR-37 narrow extension protocols. Unlike the 10 declarative
       # manifest fields, these are class-level DSLs (`node_rule` /
-      # `dynamic_return` / `type_specifier`), so they are read off the
+      # `dynamic_return` / `narrowing_facts`), so they are read off the
       # plugin class rather than the manifest. The gate values — node
       # types, receiver class names, specified method names — are the
       # greppable, enumerable surface the capability catalogue exposes.

data/lib/rigor/cli/plugins_renderer.rb

@@ -170,7 +170,7 @@ module Rigor
       end
 
       # ADR-37 narrow extension protocols (node_rule / dynamic_return /
-      # type_specifier). Surfaced in the full report alongside the
+      # narrowing_facts). Surfaced in the full report alongside the
       # declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
         lines = []

data/lib/rigor/cli/protection_renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text
@@ -12,6 +14,15 @@ module Rigor
       TOP_CALLS = 15
       TOP_FILES = 10
 
+      # ADR-73 P6 / ADR-75 WD2 — the actionable axis for each tractability
+      # category, shown next to a hole's origin so a user knows whether (and
+      # how) a type can close it.
+      TRACTABILITY_HINTS = {
+        Inference::DynamicOrigin::ADD_RBS => "add RBS",
+        Inference::DynamicOrigin::ENABLE_PLUGIN => "enable a plugin / pre_eval",
+        Inference::DynamicOrigin::ENGINE_GAP => "engine gap — report it"
+      }.freeze
+
       def initialize(out:)
         @out = out
       end
@@ -40,13 +51,32 @@ module Rigor
         return if calls.empty?
 
         @out.puts "\nAdd a type here — methods most often called on an untyped receiver:"
+        render_tractability_summary(report)
         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("  "))
+          label = origin_label(call.dynamic_origin)
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s%<label>s",
+                           count: call.count, method: call.method_name,
+                           sites: call.examples.join("  "), label: label)
         end
         @out.puts "  (#{calls.size - TOP_CALLS} more)" if calls.size > TOP_CALLS
       end
 
+      def render_tractability_summary(report)
+        summary = report.tractability_summary
+        return if summary.empty?
+
+        parts = summary.sort_by { |_, n| -n }.map { |axis, n| "#{n} #{axis.to_s.tr('_', '-')}" }
+        @out.puts "  by tractability: #{parts.join(' · ')}  (add-rbs = closable with a type)"
+      end
+
+      def origin_label(origin)
+        return "" if origin.nil?
+
+        tractability = Inference::DynamicOrigin.tractability(origin)
+        hint = tractability ? " → #{TRACTABILITY_HINTS[tractability]}" : ""
+        "  [#{origin.to_s.tr('_', '-')}#{hint}]"
+      end
+
       def render_files(report)
         worst = report.files.reject { |f| f.unprotected_count.zero? }.sort_by(&:ratio).first(TOP_FILES)
         return if worst.empty?

data/lib/rigor/cli/protection_report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner}
@@ -9,7 +11,7 @@ module Rigor
     # 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)
+    UntypedCall = Data.define(:method_name, :count, :examples, :dynamic_origin)
 
     ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors) do
       def total_protected = files.sum(&:protected_count)
@@ -17,17 +19,37 @@ module Rigor
       def grand_total = total_protected + total_unprotected
       def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
 
+      # ADR-73 P6 — total dispatch-site count per tractability axis across
+      # the classified holes (those with a recorded `dynamic_origin`), so a
+      # user sees at a glance how much of the untyped surface a type can
+      # actually close (`add_rbs`) vs. needs a plugin (`enable_plugin`) vs.
+      # is an engine gap. Keys are omitted when zero; an all-unclassified
+      # run yields `{}`.
+      def tractability_summary
+        untyped_calls.each_with_object(Hash.new(0)) do |c, acc|
+          axis = c.dynamic_origin && Inference::DynamicOrigin.tractability(c.dynamic_origin)
+          acc[axis] += c.count if axis
+        end
+      end
+
       def to_h
         {
           "protected" => total_protected,
           "unprotected" => total_unprotected,
           "protection_ratio" => ratio.round(4),
+          "tractability_summary" => tractability_summary.transform_keys(&:to_s),
           "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 }
+            entry = { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+            if c.dynamic_origin
+              entry["dynamic_origin"] = c.dynamic_origin
+              tractability = Inference::DynamicOrigin.tractability(c.dynamic_origin)
+              entry["tractability"] = tractability if tractability
+            end
+            entry
           end,
           "parse_errors" => parse_errors
         }
@@ -37,7 +59,7 @@ module Rigor
     class ProtectionAccumulator
       def initialize
         @files = []
-        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [], origins: Hash.new(0) } }
         @parse_errors = []
       end
 
@@ -50,6 +72,7 @@ module Rigor
           bucket = @calls[site.method_name]
           bucket[:count] += 1
           bucket[:examples] << "#{path}:#{site.line}" if bucket[:examples].size < 3
+          bucket[:origins][site.dynamic_origin] += 1 if site.dynamic_origin
         end
       end
 
@@ -58,9 +81,12 @@ module Rigor
       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] }
+        calls = @calls.map do |method, v|
+          origin = v[:origins].max_by { |_, count| count }&.first
+          UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples],
+                          dynamic_origin: origin)
+        end
+        untyped = calls.sort_by { |c| [-c.count, c.method_name] }
         ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors)
       end
     end

data/lib/rigor/cli/upgrade_command.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Rigor
+  class CLI
+    # `rigor upgrade` — the ADR-50 WD7 migration command skeleton.
+    #
+    # The real body lands when a concrete backwards-compatibility break
+    # gives it a target (e.g. re-running `baseline regenerate` against a
+    # strengthened default profile, surfacing renamed suppression ids,
+    # reporting `bleeding_edge:` graduations).  Until then it prints the
+    # current version and notes that upgrade is queued.
+    class UpgradeCommand < Command
+      USAGE = "Usage: rigor upgrade [options]"
+
+      # @return [Integer] CLI exit status.
+      def run
+        @out.puts("rigor upgrade: No migration target available yet (ADR-50 WD7, queued).")
+        @out.puts("Current version: #{Rigor::VERSION}")
+        0
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -43,7 +43,9 @@ module Rigor
       "skill" => :run_skill,
       "describe" => :run_describe,
       "docs" => :run_docs,
-      "show-bleedingedge" => :run_show_bleedingedge
+      "show-bleedingedge" => :run_show_bleedingedge,
+      "doctor" => :run_doctor,
+      "upgrade" => :run_upgrade
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -317,6 +319,18 @@ module Rigor
       CLI::ShowBleedingedgeCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_doctor
+      require_relative "cli/doctor_command"
+
+      CLI::DoctorCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def run_upgrade
+      require_relative "cli/upgrade_command"
+
+      CLI::UpgradeCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def help
       <<~HELP
         Usage: rigor <command> [options]
@@ -342,6 +356,8 @@ module Rigor
           skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
           docs       Print the bundled docs offline (docs <name>, docs --list)
           show-bleedingedge  Show the bleeding-edge overlay + what your config adopts (ADR-50)
+          doctor     Classify setup problems vs clean run with routed next actions (ADR-77)
+          upgrade    Migration command skeleton (ADR-50 WD7, queued)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/flow_contribution/fact.rb

@@ -18,7 +18,7 @@ module Rigor
     #    (`Rigor::RbsExtended::PredicateEffect`).
     # 3. RBS::Extended `assert*` directives
     #    (`Rigor::RbsExtended::AssertEffect`).
-    # 4. Plugin contributions via `type_specifier` DSL (ADR-52).
+    # 4. Plugin contributions via `narrowing_facts` DSL (ADR-52).
     #
     # Each of those four carriers translates to / from Fact at
     # its boundary; downstream of {Rigor::FlowContribution#to_element_list}

data/lib/rigor/inference/dynamic_origin.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-75 v1 cause set — precision-additive provenance for Dynamic[T]
+    # introduction sites.  Each symbol identifies a distinct family of
+    # reason that an expression widened to Dynamic, surfaced by
+    # `rigor coverage --protection` so users can distinguish tractable
+    # holes (e.g. an explicit `untyped` RBS signature) from intractable
+    # ones (e.g. unsupported syntax).
+    #
+    # Provenance is a side-channel: it never participates in subtyping,
+    # consistency, normalization, or erasure, and no diagnostic fires
+    # from it.
+    module DynamicOrigin
+      # A gem with no resolvable RBS.
+      EXTERNAL_GEM_WITHOUT_RBS = :external_gem_without_rbs
+      # Value across macro/DSL expansion or plugin-declared dynamic return.
+      FRAMEWORK_DSL_BOUNDARY  = :framework_dsl_boundary
+      # Budget/fuel guard widened to Dynamic.
+      ANALYZER_BUDGET_CUTOFF  = :analyzer_budget_cutoff
+      # Authored `untyped` contract.
+      EXPLICIT_UNTYPED        = :explicit_untyped
+      # Inference fallback on unmodeled construct.
+      UNSUPPORTED_SYNTAX      = :unsupported_syntax
+
+      CAUSES = [
+        EXTERNAL_GEM_WITHOUT_RBS,
+        FRAMEWORK_DSL_BOUNDARY,
+        ANALYZER_BUDGET_CUTOFF,
+        EXPLICIT_UNTYPED,
+        UNSUPPORTED_SYNTAX
+      ].freeze
+
+      # ADR-73 P6 / ADR-75 WD2 — tractability: given the cause, can a user
+      # close this `Dynamic` hole, and on which axis. `coverage --protection`
+      # surfaces it so a user does not chase a hole a hand-written type
+      # cannot fix. Three coarse, action-oriented categories:
+      #
+      # - `:add_rbs`      — write or install RBS (a missing gem signature,
+      #                     or an authored `untyped` to tighten).
+      # - `:enable_plugin`— a framework / DSL boundary; needs a plugin or
+      #                     `pre_eval:`, not a hand-written type.
+      # - `:engine_gap`   — not user-closable (a budget cutoff or unmodeled
+      #                     syntax); report it.
+      ADD_RBS       = :add_rbs
+      ENABLE_PLUGIN = :enable_plugin
+      ENGINE_GAP    = :engine_gap
+
+      TRACTABILITY = {
+        EXTERNAL_GEM_WITHOUT_RBS => ADD_RBS,
+        EXPLICIT_UNTYPED => ADD_RBS,
+        FRAMEWORK_DSL_BOUNDARY => ENABLE_PLUGIN,
+        ANALYZER_BUDGET_CUTOFF => ENGINE_GAP,
+        UNSUPPORTED_SYNTAX => ENGINE_GAP
+      }.freeze
+
+      module_function
+
+      # @return [Symbol, nil] the tractability category for a cause, or nil
+      #   when the cause is unknown / absent.
+      def tractability(cause)
+        TRACTABILITY[cause]
+      end
+    end
+  end
+end