rigortype 0.1.3 → 0.1.5

data/lib/rigor/cli/sig_gen_command.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../sig_gen"
+
+module Rigor
+  class CLI
+    # Executes the `rigor sig-gen` command — ADR-14 slices 1–3.
+    #
+    # Walks the given paths (or `configuration.paths` when none
+    # are supplied), classifies every reachable instance method
+    # via {Rigor::SigGen::Generator}, and either prints the
+    # resulting RBS skeletons / unified-style diffs (`--print`,
+    # `--diff`; slice 1) or writes them to the project signature
+    # tree via {Rigor::SigGen::Writer} (`--write`; slice 2).
+    #
+    # `--write` follows the established Ruby community
+    # convention: `lib/foo/bar.rb` → `sig/foo/bar.rbs`. New
+    # methods are inserted into the matching class declaration
+    # just before its closing `end`; new classes are appended
+    # to the file; non-existent target files are created. User-
+    # authored declarations are NEVER replaced unless
+    # `--overwrite` is set AND the candidate is a
+    # `tighter-return`.
+    #
+    # Parameter policy defaults to `untyped`. `--params=observed`
+    # (slice 3) opts in to caller-side observation harvesting:
+    # the `ObservationCollector` walks `--observe=PATH...`
+    # (default `spec/` when no flag is given AND a `spec/`
+    # directory exists), unions per-position arg types, and the
+    # generator emits the union per ADR-5 clause 2.
+    # `--params=observed-strict` stays reserved-but-inert until
+    # the capability-role catalog ships (rejected with a usage
+    # error so the surface stays stable).
+    class SigGenCommand
+      USAGE = "Usage: rigor sig-gen [options] [paths]"
+
+      VALID_MODES = %w[print diff write].freeze
+      VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
+      VALID_FORMATS = %w[text json].freeze
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        return CLI::EXIT_USAGE if options.nil?
+
+        configuration = Configuration.load(options.fetch(:config))
+        paths = @argv.empty? ? configuration.paths : @argv
+
+        observations = collect_observations(configuration, options)
+        candidates = SigGen::Generator.new(configuration: configuration, paths: paths,
+                                           observations: observations,
+                                           include_private: options.fetch(:include_private)).run
+        mode = options.fetch(:mode).to_sym
+
+        if mode == :write
+          dispatch_write(candidates, configuration, options)
+        else
+          dispatch_print_or_diff(candidates, mode, options)
+        end
+        0
+      end
+
+      private
+
+      def dispatch_print_or_diff(candidates, mode, options)
+        SigGen::Renderer.new(out: @out).render(
+          candidates: candidates,
+          mode: mode,
+          format: options.fetch(:format),
+          selection: options.fetch(:selection)
+        )
+      end
+
+      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)
+        writer = SigGen::Writer.new(path_mapper: path_mapper, overwrite: options.fetch(:overwrite))
+
+        results = writer.write_all(candidates)
+
+        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
+      end
+
+      # Slice 3 — collect call-site argument observations when
+      # `--params=observed` is set. When `--observe=PATH` is
+      # not specified, default to `spec/` (skipped silently
+      # when the directory is absent).
+      def collect_observations(configuration, options)
+        return {} if options.fetch(:params) != "observed"
+
+        observe_paths = options.fetch(:observe)
+        observe_paths = ["spec"] if observe_paths.empty? && File.directory?("spec")
+        SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths).collect
+      end
+
+      def parse_options
+        options = {
+          mode: "print",
+          format: "text",
+          params: "untyped",
+          selection: [],
+          overwrite: false,
+          observe: [],
+          include_private: false,
+          config: nil
+        }
+        build_option_parser(options).parse!(@argv)
+
+        message = validation_error(options)
+        return options if message.nil?
+
+        @err.puts("sig-gen: #{message}")
+        nil
+      end
+
+      def build_option_parser(options) # rubocop:disable Metrics/AbcSize
+        OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
+          opts.banner = USAGE
+          opts.on("--print", "Write RBS skeletons to stdout (default)") { options[:mode] = "print" }
+          opts.on("--diff", "Write a unified diff against existing RBS") { options[:mode] = "diff" }
+          opts.on("--write", "Write generated RBS to sig/<path>.rbs files") { options[:mode] = "write" }
+          opts.on("--overwrite", "Allow tighter-return updates to replace user-authored RBS") do
+            options[:overwrite] = true
+          end
+          opts.on("--include-private", "Emit private / protected instance methods (default: public only)") do
+            options[:include_private] = true
+          end
+          opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+          opts.on("--params=POLICY", "Parameter policy: untyped (default), observed, observed-strict") do |value|
+            options[:params] = value
+          end
+          opts.on("--observe=PATH", "Directory / file to scan for call-site observations (repeatable)") do |value|
+            options[:observe] << value
+          end
+          opts.on("--new-files", "Emit only new-file classifications") do
+            options[:selection] << SigGen::Classification::NEW_FILE
+          end
+          opts.on("--new-methods", "Emit only new-method classifications") do
+            options[:selection] << SigGen::Classification::NEW_METHOD
+          end
+          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 }
+        end
+      end
+
+      def validation_error(options)
+        mode = options.fetch(:mode)
+        format = options.fetch(:format)
+        params = options.fetch(:params)
+
+        return "--print, --diff, and --write are mutually exclusive flags; pick one" unless VALID_MODES.include?(mode)
+        return "unsupported --format=#{format}" unless VALID_FORMATS.include?(format)
+        return "unsupported --params=#{params}" unless VALID_PARAM_POLICIES.include?(params)
+        if params == "observed-strict"
+          return "--params=observed-strict is reserved until the capability-role catalog ships"
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_of_command.rb

@@ -61,7 +61,7 @@ module Rigor
         options
       end
 
-      def execute(target:, options:) # rubocop:disable Metrics/AbcSize
+      def execute(target:, options:)
         file, line, column = target
         return 1 unless file_exists?(file)
 

data/lib/rigor/cli/type_scan_renderer.rb

@@ -10,7 +10,7 @@ module Rigor
     # branches share a single source of truth (the `Report` value object) so
     # the two formats stay in lockstep; that pairing is why this class is a
     # bit longer than the default class-length budget.
-    class TypeScanRenderer # rubocop:disable Metrics/ClassLength
+    class TypeScanRenderer
       def initialize(out:)
         @out = out
       end

data/lib/rigor/cli/type_scan_report.rb

@@ -5,14 +5,14 @@ module Rigor
     # Aggregated report assembled by `TypeScanCommand` and consumed by
     # `TypeScanRenderer`. The struct holds per-file paths, accumulated
     # per-class counts, located fallback events, and any parse errors.
-    Report = Data.define(
+    class Report < Data.define(
       :files,
       :parse_errors,
       :visits,
       :unrecognized,
       :events,
       :options
-    ) do
+    )
       def visited_count
         visits.values.sum
       end

data/lib/rigor/cli.rb

@@ -24,7 +24,8 @@ module Rigor
       "type-of" => :run_type_of,
       "type-scan" => :run_type_scan,
       "explain" => :run_explain,
-      "diff" => :run_diff
+      "diff" => :run_diff,
+      "sig-gen" => :run_sig_gen
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -81,15 +82,36 @@ module Rigor
       runner = Analysis::Runner.new(
         configuration: configuration,
         explain: options.fetch(:explain),
-        cache_store: cache_store
+        cache_store: cache_store,
+        collect_stats: options.fetch(:stats),
+        workers: resolve_workers(options, configuration)
       )
       result = runner.run(paths)
 
       write_result(result, options.fetch(:format))
+      write_run_stats(result.stats) if result.stats
       write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
       result.success? ? 0 : 1
     end
 
+    # ADR-15 Phase 4c — resolves the worker count by
+    # precedence: CLI `--workers=N` (most explicit) > env
+    # `RIGOR_RACTOR_WORKERS` > config `.rigor.yml`
+    # `parallel.workers:` > 0 (sequential default). Returns
+    # an Integer; non-numeric values raise so typos fail
+    # loudly. CLI / env may pass a negative value — clamped
+    # to 0 (sequential) so a stray `-1` doesn't crash the
+    # pool spawn loop.
+    def resolve_workers(options, configuration)
+      cli_value = options[:workers]
+      return [Integer(cli_value), 0].max if cli_value
+
+      env_value = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+      return [Integer(env_value), 0].max if env_value && !env_value.empty?
+
+      configuration.parallel_workers
+    end
+
     def parse_check_options
       options = {
         # `nil` triggers `Configuration.discover` (`.rigor.yml` then
@@ -99,7 +121,19 @@ module Rigor
         explain: false,
         cache_stats: false,
         clear_cache: false,
-        no_cache: false
+        no_cache: false,
+        # Run-stats summary (target files, RBS class universe
+        # breakdown, wall time, peak RSS) is on by default
+        # because collection is ~free (single syscall for RSS,
+        # one walk of `class_decl_paths` for the breakdown).
+        # `--no-stats` suppresses it for callers that want a
+        # diagnostic-only output stream.
+        stats: true,
+        # ADR-15 Phase 4c — when nil, falls back to
+        # `RIGOR_RACTOR_WORKERS` then `.rigor.yml`
+        # `parallel.workers:` then 0 (sequential). See
+        # `resolve_workers` for the precedence chain.
+        workers: nil
       }
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: rigor check [options] [paths]"
@@ -109,6 +143,14 @@ module Rigor
         opts.on("--cache-stats", "Print on-disk cache inventory at end of run") { options[:cache_stats] = true }
         opts.on("--clear-cache", "Remove the .rigor/cache directory before running") { options[:clear_cache] = true }
         opts.on("--no-cache", "Disable the persistent cache for this run") { options[:no_cache] = true }
+        opts.on("--[no-]stats",
+                "Print run summary (files, classes, memory, wall time) to stderr (default: on)") do |value|
+          options[:stats] = value
+        end
+        opts.on("--workers=N", Integer,
+                "Dispatch per-file analysis across N Ractor workers (default: 0; sequential)") do |value|
+          options[:workers] = value
+        end
       end
       parser.parse!(@argv)
       options
@@ -123,6 +165,15 @@ module Rigor
       end
     end
 
+    # Emits the {Analysis::RunStats} summary to STDERR so it
+    # doesn't interleave with the diagnostic stream (text or
+    # JSON) on STDOUT. JSON consumers can pipe stdout cleanly;
+    # interactive users still see the summary on their tty.
+    def write_run_stats(stats)
+      @err.puts("")
+      stats.format(@err)
+    end
+
     def write_cache_stats(cache_root, runtime_store)
       inv = Cache::Store.disk_inventory(root: cache_root)
 
@@ -279,6 +330,12 @@ module Rigor
       DiffCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_sig_gen
+      require_relative "cli/sig_gen_command"
+
+      SigGenCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -318,6 +375,7 @@ module Rigor
           type-scan  Report Scope#type_of coverage across PATHs
           explain    Print the description of one or all CheckRules
           diff       Compare current diagnostics to a saved baseline JSON
+          sig-gen    Emit RBS skeletons inferred from .rb sources (ADR-14)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration/dependencies.rb

@@ -13,7 +13,7 @@ module Rigor
     # is read, but no analyzer machinery consumes it yet. Slice 2
     # wires `Analysis::DependencySourceInference` against this
     # value object.
-    class Dependencies # rubocop:disable Metrics/ClassLength
+    class Dependencies
       # Walking modes per
       # [ADR-10 § "Decision"](../../../docs/adr/10-dependency-source-inference.md#decision).
       VALID_MODES = %i[disabled when_missing full].freeze
@@ -61,7 +61,7 @@ module Rigor
       # walk time); `mode:` is one of {VALID_MODES}; `roots:` is
       # the list of subdirectories within the gem's installation
       # directory to walk (defaults to `["lib"]`).
-      Entry = Data.define(:gem, :mode, :roots) do
+      class Entry < Data.define(:gem, :mode, :roots)
         def disabled? = mode == :disabled
         def when_missing? = mode == :when_missing
         def full? = mode == :full

data/lib/rigor/configuration.rb

@@ -63,6 +63,81 @@ module Rigor
       "dependencies" => {
         "source_inference" => [],
         "budget_per_gem" => Configuration::Dependencies::DEFAULT_BUDGET_PER_GEM
+      },
+      "parallel" => {
+        # ADR-15 Phase 4c — when greater than zero, `rigor check`
+        # dispatches per-file analysis across N Ractor workers
+        # built around {Rigor::Analysis::WorkerSession}.
+        # `0` (default) keeps the sequential coordinator path
+        # bit-for-bit unchanged. The CLI's `--workers=N` flag
+        # and the `RIGOR_RACTOR_WORKERS` env var both override
+        # this setting; precedence is CLI > env > config > 0.
+        "workers" => 0
+      },
+      "bundler" => {
+        # Open item O4 — target-project Bundler awareness.
+        # When `bundle_path:` is set (or auto-detected), Rigor
+        # walks `<bundle_path>/ruby/*/gems/*/sig/` and adds each
+        # gem-shipped sig directory to `signature_paths:`. With
+        # O7's failure-memo in place, conflicts (a vendored sig
+        # already declares the same constant) degrade gracefully
+        # to "no RBS env" with a single-line warning naming the
+        # offending file, rather than hanging.
+        #
+        # `bundle_path:` (String, optional): explicit path to the
+        # bundler install root (e.g., "vendor/bundle" or an
+        # absolute path). Resolved relative to the project root
+        # (`paths:`'s base) when relative.
+        #
+        # `auto_detect:` (Boolean, default true): when no
+        # explicit `bundle_path:` is set, try `.bundle/config`'s
+        # `BUNDLE_PATH:` first; fall back to `vendor/bundle/`
+        # under the project root if it exists. When neither is
+        # found, no extra sigs are added — the analyzer sees
+        # only rigor's vendored RBS and the user's
+        # `signature_paths:`.
+        #
+        # O4 Layer 3 keys:
+        #
+        # `lockfile:` (String, optional): explicit path to a
+        # `Gemfile.lock`. Resolved relative to the project root
+        # when relative. When set (or auto-detected via the
+        # `auto_detect:` flag below) Rigor parses the lockfile
+        # and uses it to FILTER the bundle-discovered `sig/`
+        # directories: only gems whose `(name, version,
+        # platform)` matches a lockfile entry are admitted to
+        # `signature_paths:`. Stale or out-of-band gems sitting
+        # in the bundle install tree are silently dropped.
+        #
+        # `auto_detect:` (Boolean, also gates the lockfile
+        # search): when true and `lockfile:` is nil, look for
+        # `<project_root>/Gemfile.lock`.
+        "bundle_path" => nil,
+        "auto_detect" => true,
+        "lockfile" => nil
+      },
+      "rbs_collection" => {
+        # Open item O4 Layer 3 slice 2 — `rbs collection
+        # install` awareness. When the target project has been
+        # set up with `rbs collection install`, the resulting
+        # `rbs_collection.lock.yaml` carries the resolved (gem,
+        # version, source) triples and `.gem_rbs_collection/`
+        # holds the downloaded `.rbs` files. Rigor parses the
+        # lockfile and auto-feeds each gem's
+        # `<collection_root>/<name>/<version>/` directory into
+        # `RbsLoader`'s `signature_paths:`. Sources of type
+        # `stdlib` are skipped because rigor's bundled
+        # `DEFAULT_LIBRARIES` already covers that surface.
+        #
+        # `lockfile:` (String, optional): explicit path to
+        # `rbs_collection.lock.yaml`. Resolved relative to the
+        # project root when relative.
+        #
+        # `auto_detect:` (Boolean, default true): when no
+        # explicit `lockfile:` is set, look for
+        # `<project_root>/rbs_collection.lock.yaml`.
+        "lockfile" => nil,
+        "auto_detect" => true
       }
     }.freeze
 
@@ -78,7 +153,9 @@ module Rigor
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
-                :dependencies
+                :dependencies, :parallel_workers,
+                :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
+                :rbs_collection_lockfile, :rbs_collection_auto_detect
 
     # Loads a configuration file.
     #
@@ -214,13 +291,13 @@ module Rigor
     private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge,
                          :merge_value, :merge_dependencies_hash
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def initialize(data = DEFAULTS)
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
       @target_ruby = coerce_target_ruby(data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")))
-      @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
+      @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s).freeze
       user_excludes = Array(data.fetch("exclude", DEFAULTS.fetch("exclude"))).map(&:to_s)
       @exclude_patterns = (BUILTIN_EXCLUDES + user_excludes).uniq.freeze
       @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map do |entry|
@@ -246,10 +323,32 @@ module Rigor
       @dependencies = Dependencies.from_h(
         data.fetch("dependencies", DEFAULTS.fetch("dependencies"))
       )
+      parallel = DEFAULTS.fetch("parallel").merge(data.fetch("parallel", {}))
+      @parallel_workers = coerce_parallel_workers(parallel.fetch("workers"))
+      bundler = DEFAULTS.fetch("bundler").merge(data.fetch("bundler", {}))
+      bp = bundler.fetch("bundle_path")
+      @bundler_bundle_path = bp.nil? ? nil : bp.to_s.dup.freeze
+      @bundler_auto_detect = bundler.fetch("auto_detect") == true
+      lf = bundler.fetch("lockfile")
+      @bundler_lockfile = lf.nil? ? nil : lf.to_s.dup.freeze
+      rbs_collection = DEFAULTS.fetch("rbs_collection").merge(data.fetch("rbs_collection", {}))
+      rclf = rbs_collection.fetch("lockfile")
+      @rbs_collection_lockfile = rclf.nil? ? nil : rclf.to_s.dup.freeze
+      @rbs_collection_auto_detect = rbs_collection.fetch("auto_detect") == true
+      # Ractor migration Phase 2a: deep-freeze the
+      # Configuration so it is `Ractor.shareable?`. Every
+      # ivar above is now either a frozen value (Symbol /
+      # nil / Boolean) or an explicitly frozen
+      # collection / value object; freezing `self` makes the
+      # whole carrier safe to send across Ractor boundaries
+      # (and catches accidental post-init mutation in any
+      # caller). See
+      # `docs/design/20260514-ractor-migration.md`.
+      freeze
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-    def to_h
+    def to_h # rubocop:disable Metrics/MethodLength
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
@@ -269,7 +368,19 @@ module Rigor
         },
         "severity_profile" => severity_profile.to_s,
         "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] },
-        "dependencies" => dependencies.to_h
+        "dependencies" => dependencies.to_h,
+        "parallel" => {
+          "workers" => parallel_workers
+        },
+        "bundler" => {
+          "bundle_path" => bundler_bundle_path,
+          "auto_detect" => bundler_auto_detect,
+          "lockfile" => bundler_lockfile
+        },
+        "rbs_collection" => {
+          "lockfile" => rbs_collection_lockfile,
+          "auto_detect" => rbs_collection_auto_detect
+        }
       }
     end
 
@@ -327,6 +438,20 @@ module Rigor
     VALID_NETWORK_POLICIES = %i[disabled allowlist].freeze
     private_constant :VALID_NETWORK_POLICIES
 
+    # ADR-15 Phase 4c — accepts a non-negative Integer (or a
+    # string-shaped one from YAML files that miss type
+    # annotations). Negative / non-integer values raise so
+    # typos / bad YAML fail loudly rather than silently
+    # disabling parallelism.
+    def coerce_parallel_workers(value)
+      integer = Integer(value)
+      raise ArgumentError, "parallel.workers must be >= 0, got #{value.inspect}" if integer.negative?
+
+      integer
+    rescue TypeError, ArgumentError => e
+      raise ArgumentError, "parallel.workers must be a non-negative Integer, got #{value.inspect} (#{e.message})"
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)