rigortype 0.1.0 → 0.1.1

data/data/builtins/ruby_core/proc.yml

@@ -277,7 +277,7 @@ classes:
     singleton_methods: {}
     undefined: []
   SystemStackError:
-    parent: rb_eException
+    parent: Exception
     defined_at: references/ruby/proc.c:4593
     includes: []
     constants: {}

data/data/builtins/ruby_core/time.yml

@@ -684,7 +684,7 @@ classes:
         body_kind: composed
         cexpr_target:
         prelude_at: references/ruby/timev.rb:440
-        purity: unknown
+        purity: dispatch
         arity: -1
         cfunc:
         defined_at: references/ruby/timev.rb:440
@@ -726,7 +726,7 @@ classes:
         body_kind: composed
         cexpr_target:
         prelude_at: references/ruby/timev.rb:270
-        purity: unknown
+        purity: dispatch
         arity: -1
         cfunc:
         defined_at: references/ruby/timev.rb:270
@@ -739,7 +739,7 @@ classes:
         body_kind: composed
         cexpr_target:
         prelude_at: references/ruby/timev.rb:329
-        purity: unknown
+        purity: dispatch
         arity: -2
         cfunc:
         defined_at: references/ruby/timev.rb:329

data/lib/rigor/analysis/runner.rb

@@ -54,22 +54,45 @@ module Rigor
         Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
           @configuration.fold_platform_specific_paths
 
+        target_ruby_error = validate_target_ruby
+        return Result.new(diagnostics: [target_ruby_error]) if target_ruby_error
+
+        @plugin_registry = load_plugins
         environment = Environment.for_project(
           libraries: @configuration.libraries,
           signature_paths: @configuration.signature_paths,
-          cache_store: @cache_store
+          cache_store: @cache_store,
+          plugin_registry: @plugin_registry
         )
-
-        @plugin_registry = load_plugins
         expansion = expand_paths(paths)
 
         diagnostics = plugin_load_diagnostics
+        diagnostics += plugin_prepare_diagnostics
         diagnostics += expansion.fetch(:errors)
         diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
 
         Result.new(diagnostics: apply_severity_profile(diagnostics))
       end
 
+      # `target_ruby` flows through to Prism's `version:` option.
+      # Prism enforces the supported range and raises
+      # `ArgumentError` for versions it does not recognise. Run a
+      # one-time smoke parse here so a misconfigured target_ruby
+      # surfaces as a single project-level diagnostic instead of
+      # crashing the whole run on the first file.
+      def validate_target_ruby
+        Prism.parse("nil", version: @configuration.target_ruby)
+        nil
+      rescue ArgumentError => e
+        Diagnostic.new(
+          path: ".rigor.yml", line: 1, column: 1,
+          message: "target_ruby #{@configuration.target_ruby.inspect} is not accepted by Prism: #{e.message}",
+          severity: :error,
+          rule: "configuration-error",
+          source_family: :builtin
+        )
+      end
+
       private
 
       # Loads project-configured plugins through {Rigor::Plugin::Loader}
@@ -183,6 +206,47 @@ module Rigor
         end
       end
 
+      # ADR-9 slice 3 — invokes every loaded plugin's `#prepare`
+      # hook once per run, after the loader's `#init` pass and
+      # before per-file iteration. Plugins publish facts here
+      # for cross-plugin consumption via the shared
+      # `services.fact_store`. Failures isolate as
+      # `:plugin_loader runtime-error` diagnostics, mirroring the
+      # `#diagnostics_for_file` raise envelope in
+      # `plugin_runtime_error_diagnostic`.
+      #
+      # Slice 3 visits plugins in registration order. Slice 5
+      # introduces topological ordering by `manifest(consumes:)`
+      # so producers always run before consumers; until then,
+      # `Configuration#plugins` order MUST be producer-first if
+      # cross-plugin dependencies exist.
+      def plugin_prepare_diagnostics
+        return [] if @plugin_registry.empty?
+
+        @plugin_registry.plugins.flat_map { |plugin| invoke_plugin_prepare(plugin) }
+      end
+
+      def invoke_plugin_prepare(plugin)
+        plugin.prepare(plugin.services)
+        []
+      rescue StandardError => e
+        [plugin_prepare_error_diagnostic(plugin, e)]
+      end
+
+      def plugin_prepare_error_diagnostic(plugin, error)
+        plugin_id = safe_plugin_id(plugin)
+        Diagnostic.new(
+          path: ".rigor.yml",
+          line: 1,
+          column: 1,
+          message: "plugin #{plugin_id.inspect} raised during prepare: " \
+                   "#{error.class}: #{error.message}",
+          severity: :error,
+          rule: "runtime-error",
+          source_family: :plugin_loader
+        )
+      end
+
       # ADR-7 § "Slice 5-A/5-B" — invokes every loaded plugin's
       # per-file diagnostic emission hook
       # (`Plugin::Base#diagnostics_for_file`) and re-stamps the
@@ -254,7 +318,7 @@ module Rigor
         errors = []
         Array(paths).each do |path|
           if File.directory?(path)
-            files.concat(Dir.glob(File.join(path, RUBY_GLOB)))
+            files.concat(reject_excluded(Dir.glob(File.join(path, RUBY_GLOB))))
           elsif File.file?(path) && path.end_with?(".rb")
             files << path
           elsif File.exist?(path)
@@ -266,6 +330,25 @@ module Rigor
         { files: files, errors: errors }
       end
 
+      # `Configuration#exclude_patterns` is a list of glob patterns
+      # checked against each globbed path via `File.fnmatch?` (without
+      # `FNM_PATHNAME`, so `**` and `*` both span path separators —
+      # the patterns behave like substring globs). Built-in defaults
+      # exclude `vendor/bundle`, `.bundle`, `node_modules`, and `tmp`
+      # so the analyser never walks into vendored deps or build
+      # artefacts. User-supplied entries (`.rigor.yml` `exclude:`)
+      # layer on top. Explicit file arguments to the CLI bypass this
+      # filter — only the directory-glob expansion is filtered.
+      def reject_excluded(file_list)
+        return file_list if @configuration.exclude_patterns.empty?
+
+        file_list.reject { |path| excluded?(path) }
+      end
+
+      def excluded?(path)
+        @configuration.exclude_patterns.any? { |pattern| File.fnmatch?(pattern, path) }
+      end
+
       def path_error(path, message)
         Diagnostic.new(
           path: path,
@@ -277,7 +360,7 @@ module Rigor
       end
 
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
-        parse_result = Prism.parse_file(path)
+        parse_result = Prism.parse_file(path, version: @configuration.target_ruby)
         return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
 
         scope = Scope.empty(environment: environment)

data/lib/rigor/builtins/regex_refinement.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Maps a curated table of canonical regex sub-patterns onto the
+    # imported refinement carriers Rigor already ships
+    # (`decimal-int-string`, `hex-int-string`, `octal-int-string`,
+    # `lowercase-string`, `uppercase-string`, `numeric-string`).
+    # See `docs/type-specification/imported-built-in-types.md` for
+    # the registry the refinements come from and `docs/MILESTONES.md`
+    # § "v0.1.1 — Planned" Track 1 slice 1 for the binding scope of
+    # this recogniser.
+    #
+    # The intended consumer is `Inference::Narrowing.analyse_match_write`:
+    # given `if /(?<year>\d+)/ =~ str; year; end`, the v0.1.0
+    # baseline narrows `year` to plain `String`; v0.1.1 introspects
+    # the regex source and narrows further to
+    # `decimal-int-string` whenever the named-capture body matches
+    # one of the rows in {RULES}.
+    #
+    # Recognised body shapes (each row admits the `+` quantifier
+    # and the bounded `{n}` / `{n,m}` forms with `n >= 1`):
+    #
+    #   - `\d`                     -> decimal-int-string
+    #   - `\h`                     -> hex-int-string
+    #   - `[0-9a-fA-F]`            -> hex-int-string
+    #   - `[0-9a-f]`, `[0-9A-F]`   -> hex-int-string
+    #   - `[0-7]`                  -> octal-int-string
+    #   - `[a-z]`                  -> lowercase-string
+    #   - `[A-Z]`                  -> uppercase-string
+    #   - `[[:digit:]]`            -> numeric-string
+    #
+    # Anything outside the table returns `nil` so the calling
+    # narrowing site falls back to its previous behaviour
+    # (plain `String`). Arbitrary regex semantic equivalence is
+    # undecidable, so the table is intentionally a small audited
+    # set of canonical shapes rather than a general equivalence
+    # checker.
+    module RegexRefinement
+      # `+` (one-or-more) or `{n}` / `{n,m}` (n >= 1, m >= n).
+      # The bound check is enforced separately by
+      # {valid_bounds?} after the structural match succeeds, so
+      # forms like `\d{0,5}` or `\d{5,3}` reject even though they
+      # parse syntactically.
+      QUANTIFIER_SOURCE = '(?:\+|\{\d+(?:,\d+)?\})'
+      private_constant :QUANTIFIER_SOURCE
+
+      RULES = [
+        [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
+        [/\A\\h#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9a-fA-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9a-f\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-9A-F\]#{QUANTIFIER_SOURCE}\z/, :hex_int_string],
+        [/\A\[0-7\]#{QUANTIFIER_SOURCE}\z/, :octal_int_string],
+        [/\A\[a-z\]#{QUANTIFIER_SOURCE}\z/, :lowercase_string],
+        [/\A\[A-Z\]#{QUANTIFIER_SOURCE}\z/, :uppercase_string],
+        [/\A\[\[:digit:\]\]#{QUANTIFIER_SOURCE}\z/, :numeric_string]
+      ].freeze
+      private_constant :RULES
+
+      BOUND_RE = /\{(\d+)(?:,(\d+))?\}\z/
+      private_constant :BOUND_RE
+
+      module_function
+
+      # @param body [String, nil] a regex sub-pattern, typically the
+      #   inner body of a `(?<name>body)` named capture. Anchors
+      #   (`\A`, `\z`, `^`, `$`) are not stripped — the recogniser
+      #   table targets bodies that the regex engine treats as
+      #   anchored to the capture group bounds.
+      # @return [Rigor::Type, nil] the matching imported refinement
+      #   carrier, or `nil` if `body` is not a recognised shape.
+      def for_capture_body(body)
+        return nil if body.nil? || body.empty?
+
+        rule = RULES.find { |pattern, _| pattern.match?(body) }
+        return nil if rule.nil?
+        return nil unless valid_bounds?(body)
+
+        Type::Combinator.public_send(rule.last)
+      end
+
+      # Filters the bounded-quantifier forms to ones whose lower
+      # bound is at least 1 and whose upper bound (if any) is at
+      # least the lower bound. Without this, `\d{0,5}` would be
+      # accepted even though it admits the empty string, which is
+      # not a valid `decimal-int-string`.
+      def valid_bounds?(body)
+        m = BOUND_RE.match(body)
+        return true if m.nil?
+
+        low = Integer(m[1])
+        return false if low < 1
+
+        high = m[2] && Integer(m[2])
+        return true if high.nil?
+
+        low <= high
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_of_command.rb

@@ -48,7 +48,7 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", trace: false, config: Configuration::DEFAULT_PATH }
+        options = { format: "text", trace: false, config: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
@@ -65,8 +65,9 @@ module Rigor
         file, line, column = target
         return 1 unless file_exists?(file)
 
+        configuration = Configuration.load(options.fetch(:config))
         source = File.read(file)
-        parse_result = Prism.parse(source, filepath: file)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
         return 1 if parse_errors?(parse_result, file)
 
         node = locate_node(source: source, root: parse_result.value, file: file, line: line, column: column)
@@ -74,7 +75,6 @@ module Rigor
         return 1 if node.nil?
 
         tracer = options[:trace] ? Inference::FallbackTracer.new : nil
-        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

data/lib/rigor/cli/type_scan_command.rb

@@ -46,7 +46,7 @@ module Rigor
 
       def parse_options
         options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
-                    config: Configuration::DEFAULT_PATH }
+                    config: nil }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
@@ -93,7 +93,7 @@ module Rigor
         scope = Scope.empty(environment: project_environment(configuration))
         scanner = Inference::CoverageScanner.new(scope: scope)
         accumulator = ScanAccumulator.new
-        paths.each { |path| scan_one(path, scanner, accumulator) }
+        paths.each { |path| scan_one(path, scanner, accumulator, configuration) }
         accumulator.to_report(paths, options)
       end
 
@@ -107,9 +107,9 @@ module Rigor
         )
       end
 
-      def scan_one(path, scanner, accumulator)
+      def scan_one(path, scanner, accumulator, configuration)
         source = File.read(path)
-        parse_result = Prism.parse(source, filepath: path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
         if parse_result.errors.any?
           accumulator.record_parse_error(path, parse_result.errors)
           return

data/lib/rigor/cli.rb

@@ -70,11 +70,11 @@ module Rigor
 
       options = parse_check_options
 
-      cache_root = ".rigor/cache"
+      configuration = Configuration.load(options.fetch(:config))
+      cache_root = configuration.cache_path
       handle_clear_cache(cache_root) if options.fetch(:clear_cache)
       cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
 
-      configuration = Configuration.load(options.fetch(:config))
       paths = @argv.empty? ? configuration.paths : @argv
       runner = Analysis::Runner.new(
         configuration: configuration,
@@ -90,7 +90,9 @@ module Rigor
 
     def parse_check_options
       options = {
-        config: Configuration::DEFAULT_PATH,
+        # `nil` triggers `Configuration.discover` (`.rigor.yml` then
+        # `.rigor.dist.yml`); an explicit `--config=PATH` overrides.
+        config: nil,
         format: "text",
         explain: false,
         cache_stats: false,
@@ -170,9 +172,14 @@ module Rigor
     end
 
     def run_init
+      # Default destination is `.rigor.dist.yml` — the
+      # project-default config that gets committed. Developers
+      # who want a personal override layer create `.rigor.yml`
+      # alongside it (auto-discovery prefers `.rigor.yml` when
+      # both are present; no implicit merge).
       options = {
         force: false,
-        path: Configuration::DEFAULT_PATH
+        path: ".rigor.dist.yml"
       }
 
       parser = OptionParser.new do |opts|

data/lib/rigor/configuration.rb

@@ -6,10 +6,44 @@ require_relative "configuration/severity_profile"
 
 module Rigor
   class Configuration # rubocop:disable Metrics/ClassLength
-    DEFAULT_PATH = ".rigor.yml"
+    # File-discovery order for `Configuration.load(nil)`.
+    #
+    # The first file present is loaded; the others are NOT
+    # implicitly merged. To extend a base config explicitly the
+    # winning file MUST list the base via `includes:`.
+    #
+    # `.rigor.yml` is a developer-local override (typically
+    # gitignored); `.rigor.dist.yml` is the project default
+    # (committed to the repo). When both are present the
+    # developer's local override wins outright — there is no
+    # implicit auto-merge.
+    DISCOVERY_ORDER = %w[.rigor.yml .rigor.dist.yml].freeze
+    # Back-compat alias. Keep here so external callers that read
+    # `Configuration::DEFAULT_PATH` for help text / fixture paths
+    # still work; the discovery list is the canonical source.
+    DEFAULT_PATH = DISCOVERY_ORDER.first
+
+    # Built-in exclusion patterns appended to `exclude:` so vendored
+    # dependencies, Bundler artefacts, and JavaScript node_modules are
+    # never analysed by accident when a directory glob expands. Users
+    # cannot disable these defaults; the trade-off is that analysing
+    # any of these paths is essentially never what the user wants
+    # (they're build outputs / external dependencies, not source).
+    #
+    # We deliberately keep this list narrow. `tmp/` and similar
+    # directories vary across project layouts (Rails has `tmp/`,
+    # libraries usually don't); user-supplied `exclude:` entries
+    # in `.rigor.yml` cover the project-specific cases.
+    BUILTIN_EXCLUDES = %w[
+      **/vendor/bundle/**
+      **/.bundle/**
+      **/node_modules/**
+    ].freeze
+
     DEFAULTS = {
       "target_ruby" => "4.0",
       "paths" => ["lib"],
+      "exclude" => [],
       "plugins" => [],
       "disable" => [],
       "libraries" => [],
@@ -26,27 +60,136 @@ module Rigor
       "severity_overrides" => {}
     }.freeze
 
-    attr_reader :target_ruby, :paths, :plugins, :cache_path, :disabled_rules,
+    # Top-level keys whose values are file/directory paths that
+    # MUST be resolved relative to the config file's directory.
+    # `exclude:` is intentionally NOT in this list — its entries
+    # are glob patterns (`**/vendor/**`), not paths.
+    PATH_KEYS = %w[paths signature_paths].freeze
+    private_constant :PATH_KEYS
+
+    attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
                 :libraries, :signature_paths, :fold_platform_specific_paths,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :severity_profile, :severity_overrides
 
-    def self.load(path = DEFAULT_PATH)
-      data = if File.exist?(path)
-               YAML.safe_load_file(path, aliases: false) || {}
-             else
-               {}
-             end
+    # Loads a configuration file.
+    #
+    # `path == nil` triggers auto-discovery against
+    # {DISCOVERY_ORDER}. The first present file in that list is
+    # loaded; if none exist the built-in {DEFAULTS} are used.
+    #
+    # When a path is supplied (whether by auto-discovery or by
+    # the caller) the YAML body is processed for `includes:`
+    # recursively, and every relative path inside path-bearing
+    # keys (`paths:`, `signature_paths:`, `plugins_io.allowed_paths:`,
+    # `includes:`) is resolved against THAT file's directory.
+    # The resolution is per-file: an included file's relative
+    # paths resolve against the included file's directory, not
+    # the top-level file. Path resolution mirrors
+    # [PHPStan](https://phpstan.org/config-reference#paths).
+    def self.load(path = nil)
+      resolved = path || discover
+      return new(DEFAULTS) if resolved.nil? || !File.exist?(resolved)
 
+      data = load_with_includes(resolved)
       new(DEFAULTS.merge(data))
     end
 
-    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+    # Returns the path to the config file Rigor would load
+    # under auto-discovery, or `nil` when neither candidate
+    # exists. Public so the CLI / spec drift checks can
+    # introspect the resolved file.
+    def self.discover
+      DISCOVERY_ORDER.find { |candidate| File.exist?(candidate) }
+    end
+
+    # Reads `path` (which MUST exist) plus every file listed in
+    # its `includes:` chain, merging them under the order:
+    # included files first (in declaration order), then the
+    # current file's own keys override. Relative paths inside
+    # each file are resolved against that file's directory.
+    def self.load_with_includes(path, visited: Set.new)
+      absolute = File.expand_path(path)
+      raise ArgumentError, "circular include: #{absolute}" if visited.include?(absolute)
+
+      raw = YAML.safe_load_file(absolute, aliases: false) || {}
+      raise ArgumentError, "config file must be a YAML mapping: #{absolute}" unless raw.is_a?(Hash)
+
+      base_dir = File.dirname(absolute)
+      includes = Array(raw.delete("includes") || [])
+      data = resolve_paths_in(raw, base_dir)
+      next_visited = visited + [absolute]
+      merge_includes(data, includes, base_dir, next_visited)
+    end
+
+    def self.merge_includes(data, includes, base_dir, visited)
+      return data if includes.empty?
+
+      accumulated = {}
+      includes.each do |inc|
+        inc_path = File.expand_path(inc.to_s, base_dir)
+        unless File.exist?(inc_path)
+          raise ArgumentError, "include not found: #{inc.inspect} (referenced from #{base_dir})"
+        end
+
+        accumulated = deep_merge(accumulated, load_with_includes(inc_path, visited: visited))
+      end
+      deep_merge(accumulated, data)
+    end
+
+    # Per-file path resolution. Each path-bearing key listed in
+    # {PATH_KEYS} plus the nested `plugins_io.allowed_paths:`
+    # entries get their relative paths expanded against the
+    # config file's directory. `cache.path:` is intentionally
+    # left as-is so end-user messages (e.g. `--cache-stats`
+    # output) keep the project-relative form the user wrote.
+    def self.resolve_paths_in(data, base_dir)
+      return data unless data.is_a?(Hash)
+
+      out = data.dup
+      PATH_KEYS.each { |key| resolve_path_key!(out, key, base_dir) }
+      resolve_plugins_io_paths!(out, base_dir)
+      out
+    end
+
+    def self.resolve_path_key!(out, key, base_dir)
+      return unless out.key?(key) && !out[key].nil?
+
+      out[key] = Array(out[key]).map { |p| File.expand_path(p.to_s, base_dir) }
+    end
+
+    def self.resolve_plugins_io_paths!(out, base_dir)
+      plugins_io = out["plugins_io"]
+      return unless plugins_io.is_a?(Hash) && plugins_io["allowed_paths"]
+
+      duped = plugins_io.dup
+      duped["allowed_paths"] = Array(plugins_io["allowed_paths"]).map { |p| File.expand_path(p.to_s, base_dir) }
+      out["plugins_io"] = duped
+    end
+
+    def self.deep_merge(left, right)
+      return right unless left.is_a?(Hash) && right.is_a?(Hash)
+
+      merged = left.dup
+      right.each do |key, value|
+        merged[key] = if merged.key?(key) && merged[key].is_a?(Hash) && value.is_a?(Hash)
+                        deep_merge(merged[key], value)
+                      else
+                        value
+                      end
+      end
+      merged
+    end
+    private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge
+
+    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
-      @target_ruby = data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")).to_s
+      @target_ruby = coerce_target_ruby(data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")))
       @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
+      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|
         coerce_plugin_entry(entry)
       end.freeze
@@ -72,6 +215,7 @@ module Rigor
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
+        "exclude" => exclude_patterns - BUILTIN_EXCLUDES,
         "plugins" => plugins,
         "disable" => disabled_rules,
         "libraries" => libraries,
@@ -107,6 +251,29 @@ module Rigor
       end
     end
 
+    # `target_ruby` is passed to `Prism.parse_file(path, version:)` at
+    # the analyser's three parse sites (`Analysis::Runner`,
+    # `CLI::TypeOfCommand`, `CLI::TypeScanCommand`) so projects that
+    # target an older Ruby get parse errors for syntax their target
+    # doesn't support. Format validation here is loose — accepts
+    # any `<major>.<minor>` or `<major>.<minor>.<patch>` form, plus
+    # the literal `"latest"`. Prism itself enforces the supported
+    # set and raises `ArgumentError` for versions it does not
+    # recognise (e.g. `"1.0"`); the parse-time error message names
+    # the version, so the user can correct the setting.
+    TARGET_RUBY_FORMAT = /\A(?:\d+\.\d+(?:\.\d+)?|latest)\z/
+    private_constant :TARGET_RUBY_FORMAT
+
+    def coerce_target_ruby(value)
+      s = value.to_s
+      unless s.match?(TARGET_RUBY_FORMAT)
+        raise ArgumentError,
+              "target_ruby must be a version (e.g. \"3.4\", \"4.0\", \"3.4.0\") or \"latest\", got #{value.inspect}"
+      end
+
+      s.dup.freeze
+    end
+
     # Slice 2 only accepts `:disabled` for the network policy. The
     # YAML scalar may arrive as a String (`"disabled"`) or already
     # as the Symbol; coerce to the canonical Symbol shape so the

data/lib/rigor/environment.rb

@@ -41,7 +41,7 @@ module Rigor
       prism rbs
     ].freeze
 
-    attr_reader :class_registry, :rbs_loader
+    attr_reader :class_registry, :rbs_loader, :plugin_registry
 
     # @param class_registry [Rigor::Environment::ClassRegistry]
     # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the
@@ -50,9 +50,17 @@ module Rigor
     #   wires the shared core loader, which is itself lazy: requesting an
     #   environment instance does NOT load RBS until a method or class
     #   query actually consults the loader.
-    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil)
+    # @param plugin_registry [Rigor::Plugin::Registry, nil] v0.1.1
+    #   Track 2 slice 7. The per-run plugin registry the
+    #   inference engine consults at call sites for plugin
+    #   `#flow_contribution_for` overrides. When nil (the
+    #   default), no plugin-level return-type contribution
+    #   participates — useful for tests, the `Environment.default`
+    #   facade, and analyses that don't load plugins.
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, plugin_registry: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
+      @plugin_registry = plugin_registry
       freeze
     end
 
@@ -82,7 +90,7 @@ module Rigor
       #   reflection artefacts) consult the cache. Pass `nil` (the
       #   default) to skip caching for this environment.
       # @return [Rigor::Environment]
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil)
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, plugin_registry: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
         loader = RbsLoader.new(
@@ -90,7 +98,7 @@ module Rigor
           signature_paths: resolved_paths,
           cache_store: cache_store
         )
-        new(rbs_loader: loader)
+        new(rbs_loader: loader, plugin_registry: plugin_registry)
       end
 
       private

data/lib/rigor/inference/expression_typer.rb

@@ -981,7 +981,9 @@ module Rigor
           method_name: node.name,
           arg_types: arg_types,
           block_type: block_type,
-          environment: scope.environment
+          environment: scope.environment,
+          call_node: node,
+          scope: scope
         )
         return result if result