rigortype 0.1.4 → 0.1.6

data/lib/rigor/analysis/worker_session.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../cache/store"
+require_relative "../plugin"
+require_relative "../rbs_extended/reporter"
+require_relative "../reflection"
+require_relative "../type/combinator"
+require_relative "../inference/coverage_scanner"
+require_relative "../inference/scope_indexer"
+require_relative "../inference/method_dispatcher/file_folding"
+require_relative "check_rules"
+require_relative "dependency_source_inference"
+require_relative "diagnostic"
+
+module Rigor
+  module Analysis
+    # ADR-15 Phase 4a — per-worker analysis substrate.
+    # [ADR-15](../../../docs/adr/15-ractor-concurrency.md)
+    # § Phase 4 carves the eventual Ractor-isolated worker pool
+    # into three sub-phases; this is the substrate that 4b will
+    # wrap in `Ractor.new` and 4c will gate behind
+    # `RIGOR_RACTOR_WORKERS`. NO Ractor in the loop yet — 4a
+    # exists so the per-worker ownership boundary is testable in
+    # the absence of any Ractor coordination.
+    #
+    # The constructor takes only `Ractor.shareable?` inputs:
+    #
+    # - `configuration` — Phase 2a ({Rigor::Configuration} is
+    #   `Ractor.shareable?`).
+    # - `cache_store` — frozen-shareable handle is NOT a precondition;
+    #   future 4b workers build their OWN Store at the shared
+    #   `cache_root` directory. 4a accepts an already-built Store
+    #   for the no-Ractor coordinator path.
+    # - `plugin_blueprints` — Phase 3a
+    #   (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
+    # - `explain` — Boolean.
+    #
+    # Internally the session OWNS (and never shares):
+    #
+    # - {Rigor::Plugin::Services} bound to the per-worker Store.
+    # - {Rigor::Plugin::Registry} materialised from the blueprints
+    #   via {Rigor::Plugin::Registry.materialize}; each plugin
+    #   instance, with its mutable per-run accumulators
+    #   (`@reachable_absurd_nodes`, `*_index`, …) lives entirely
+    #   inside this session.
+    # - {Rigor::RbsExtended::Reporter} +
+    #   {Rigor::Analysis::DependencySourceInference::BoundaryCrossReporter}
+    #   (Mutex-bearing; intentionally per-worker — the runner
+    #   merges entries post-pool via {#drain_reporters}).
+    # - {Rigor::Environment} threaded with the per-worker reporters
+    #   so reporter writes from inference / dispatcher accumulate
+    #   into the worker's own state.
+    #
+    # Plugin `prepare` runs ONCE at construction time so each
+    # worker is "warm" by the time `#analyze` is first called. Any
+    # raise from `prepare` is captured into {#prepare_diagnostics}
+    # so the runner can surface them alongside the per-file
+    # diagnostic stream.
+    #
+    # Equivalence contract (proven by spec): given identical
+    # `(configuration, cache_store, plugin_blueprints)`, the
+    # multiset of diagnostics from
+    # `paths.flat_map { |p| session.analyze(p) }` plus
+    # {#prepare_diagnostics} plus reporter drains MUST equal the
+    # corresponding subset of {Rigor::Analysis::Runner#run}'s
+    # output (modulo severity-profile re-stamping, which the
+    # session leaves to the caller because it is a per-run
+    # aggregate concern).
+    class WorkerSession
+      attr_reader :configuration, :cache_store, :services, :plugin_registry,
+                  :dependency_source_index, :environment,
+                  :rbs_extended_reporter, :boundary_cross_reporter,
+                  :prepare_diagnostics
+
+      # @param configuration [Rigor::Configuration]
+      # @param cache_store [Rigor::Cache::Store, nil] persistent
+      #   cache the session exposes to plugin-side producers and
+      #   the RBS loader. Pass `nil` to disable caching.
+      # @param plugin_blueprints [Array<Rigor::Plugin::Blueprint>]
+      #   replay descriptors. Empty array yields a session with
+      #   no plugin contributions.
+      # @param explain [Boolean] when true, `#analyze` additionally
+      #   emits one `:info` `fallback` diagnostic per
+      #   directly-unrecognised node, mirroring
+      #   {Rigor::Analysis::Runner#explain_diagnostics}.
+      def initialize(configuration:, cache_store: nil, # rubocop:disable Metrics/MethodLength
+                     plugin_blueprints: [], explain: false, buffer: nil)
+        @configuration = configuration
+        @cache_store = cache_store
+        @explain = explain
+        @buffer = buffer
+
+        # NOTE: `Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths`
+        # is process-global state. Writing it from a non-main
+        # Ractor would raise `Ractor::IsolationError`, so the
+        # session does NOT touch it — the CALLER (typically
+        # {Rigor::Analysis::Runner#run}) is responsible for
+        # setting it on the main Ractor before spawning the
+        # pool. The substrate stays Ractor-safe by construction.
+        @rbs_extended_reporter = RbsExtended::Reporter.new
+        @boundary_cross_reporter = DependencySourceInference::BoundaryCrossReporter.new
+        @dependency_source_index = DependencySourceInference::Builder.build(configuration.dependencies)
+
+        @services = Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: cache_store,
+          trust_policy: build_trust_policy
+        )
+        @plugin_registry = Plugin::Registry.materialize(
+          blueprints: plugin_blueprints, services: @services
+        )
+        @environment = Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths,
+          cache_store: cache_store,
+          plugin_registry: @plugin_registry,
+          dependency_source_index: @dependency_source_index,
+          rbs_extended_reporter: @rbs_extended_reporter,
+          boundary_cross_reporter: @boundary_cross_reporter,
+          bundler_bundle_path: configuration.bundler_bundle_path,
+          bundler_auto_detect: configuration.bundler_auto_detect,
+          bundler_lockfile: configuration.bundler_lockfile,
+          rbs_collection_lockfile: configuration.rbs_collection_lockfile,
+          rbs_collection_auto_detect: configuration.rbs_collection_auto_detect
+        )
+        @prepare_diagnostics = run_plugin_prepare.freeze
+      end
+
+      # Equivalent of {Rigor::Analysis::Runner#analyze_file} +
+      # `plugin_emitted_diagnostics` + `explain_diagnostics`.
+      # Returns a flat `Array<Diagnostic>` for the file. Severity
+      # profile re-stamping is intentionally NOT applied — that
+      # is a per-run aggregate concern handled by the caller.
+      def analyze(path)
+        parse_result = parse_source(path)
+        return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
+
+        scope = Scope.empty(environment: @environment, source_path: path)
+        index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        diagnostics = CheckRules.diagnose(
+          path: path,
+          root: parse_result.value,
+          scope_index: index,
+          comments: parse_result.comments,
+          disabled_rules: @configuration.disabled_rules
+        )
+        diagnostics += plugin_emitted_diagnostics(path, parse_result.value, scope)
+        diagnostics + explain_diagnostics(path, parse_result.value, scope)
+      rescue Errno::ENOENT => e
+        [analyzer_error(path, e.message)]
+      rescue StandardError => e
+        [analyzer_error(path, "internal analyzer error: #{e.class}: #{e.message}")]
+      end
+
+      # Read-once snapshot of the per-worker reporters so the
+      # caller (or the eventual Phase 4b pool aggregator) can
+      # merge into a single coordinator-side reporter. Both
+      # reporters dedupe at write time, so a post-hoc concat +
+      # de-dup at the entry-key level is sound.
+      def drain_reporters
+        {
+          rbs_extended: {
+            unresolved_payloads: @rbs_extended_reporter.unresolved_payloads,
+            lossy_projections: @rbs_extended_reporter.lossy_projections
+          },
+          boundary_cross: @boundary_cross_reporter.entries
+        }
+      end
+
+      private
+
+      # See {Runner#parse_source}. Same contract: if `@buffer`
+      # binds `path` to a physical file, read the physical bytes
+      # but stamp the parse buffer's `filepath:` as the LOGICAL
+      # path so downstream diagnostics carry the logical path.
+      def parse_source(path)
+        physical = @buffer ? @buffer.resolve(path) : path
+        return Prism.parse_file(physical, version: @configuration.target_ruby) if physical == path
+
+        Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
+      end
+
+      # Mirrors {Runner#build_trust_policy}. Workers under Phase
+      # 4b will need the same trust derivation, and the
+      # configuration is already shareable, so deriving it inside
+      # the session keeps the substrate decoupled from the
+      # coordinator's helper.
+      def build_trust_policy
+        trusted_gems = @configuration.plugins.map { |entry| trusted_gem_name(entry) }.uniq
+        roots = [Dir.pwd]
+        Array(@configuration.signature_paths).each { |sp| roots << File.expand_path(sp) }
+        trusted_gems.each do |gem_name|
+          path = trusted_gem_root(gem_name)
+          roots << path if path
+        end
+        @configuration.plugins_io_allowed_paths.each { |p| roots << File.expand_path(p) }
+
+        Plugin::TrustPolicy.new(
+          trusted_gems: trusted_gems,
+          allowed_read_roots: roots,
+          network_policy: @configuration.plugins_io_network,
+          allowed_url_hosts: @configuration.plugins_io_allowed_url_hosts
+        )
+      end
+
+      def trusted_gem_name(entry)
+        case entry
+        when String then entry
+        when Hash then entry["gem"] || entry["id"]
+        end
+      end
+
+      def trusted_gem_root(gem_name)
+        return nil if gem_name.nil? || gem_name.empty?
+
+        spec = Gem.loaded_specs[gem_name]
+        spec&.full_gem_path # rigor:disable undefined-method
+      rescue StandardError
+        nil
+      end
+
+      def run_plugin_prepare
+        return [] if @plugin_registry.empty?
+
+        @plugin_registry.plugins.flat_map do |plugin|
+          plugin.prepare(plugin.services)
+          []
+        rescue StandardError => e
+          [plugin_prepare_error_diagnostic(plugin, e)]
+        end
+      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
+
+      def plugin_emitted_diagnostics(path, root, scope)
+        return [] if @plugin_registry.empty?
+
+        @plugin_registry.plugins.flat_map do |plugin|
+          collect_plugin_diagnostics(plugin, path, root, scope)
+        end
+      end
+
+      def collect_plugin_diagnostics(plugin, path, root, scope)
+        raw = plugin.diagnostics_for_file(path: path, scope: scope, root: root)
+        Array(raw).map { |diagnostic| stamp_plugin_diagnostic(diagnostic, plugin.manifest.id) }
+      rescue StandardError => e
+        [plugin_runtime_error_diagnostic(path, plugin, e)]
+      end
+
+      def stamp_plugin_diagnostic(diagnostic, plugin_id)
+        Diagnostic.new(
+          path: diagnostic.path,
+          line: diagnostic.line,
+          column: diagnostic.column,
+          message: diagnostic.message,
+          severity: diagnostic.severity,
+          rule: diagnostic.rule,
+          source_family: "plugin.#{plugin_id}"
+        )
+      end
+
+      def plugin_runtime_error_diagnostic(path, plugin, error)
+        plugin_id = safe_plugin_id(plugin)
+        Diagnostic.new(
+          path: path,
+          line: 1,
+          column: 1,
+          message: "plugin #{plugin_id.inspect} raised during diagnostics_for_file: " \
+                   "#{error.class}: #{error.message}",
+          severity: :error,
+          rule: "runtime-error",
+          source_family: :plugin_loader
+        )
+      end
+
+      def safe_plugin_id(plugin)
+        plugin.manifest.id
+      rescue StandardError
+        plugin.class.to_s
+      end
+
+      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
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: error.message,
+            severity: :error
+          )
+        end
+      end
+
+      def analyzer_error(path, message)
+        Diagnostic.new(path: path, line: 1, column: 1, message: message, severity: :error)
+      end
+    end
+  end
+end

data/lib/rigor/builtins/hkt_builtins.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require_relative "../inference/hkt_registry"
+require_relative "../inference/hkt_body"
+require_relative "../inference/hkt_body_parser"
+
+module Rigor
+  module Builtins
+    # ADR-20 slices 2c + 3 — Rigor-bundled Lightweight HKT
+    # registrations that ship with every analyzer instance.
+    # The set is intentionally small at v0.1.x: only the URIs
+    # whose payoff justifies hardcoded definitions. Plugin
+    # authors register more URIs through their manifests; user
+    # `.rbs` overlays register through the
+    # `%a{rigor:v1:hkt_register}` /
+    # `%a{rigor:v1:hkt_define}` annotations Slice 1 ships.
+    #
+    # Today's contents:
+    #
+    # - `json::value[K]` — the recursive sum stdlib's
+    #   `JSON.parse` returns. Body:
+    #
+    #     nil | true | false | Integer | Float | String
+    #     | Array[App[json::value, K]]
+    #     | Hash[K, App[json::value, K]]
+    #
+    #   The reducer handles the self-recursive `App` nodes via
+    #   lazy "tying-the-knot" (see {HktReducer}). `K = String`
+    #   matches stdlib's default key handling; `K = Symbol`
+    #   matches `symbolize_names: true`.
+    module HktBuiltins
+      module_function
+
+      # Built via the body-string parser (slice 2b/2c) so the
+      # bundled overlay exercises the same authoring surface
+      # third-party plugins use. The body matches what user
+      # `.rbs` overlays would write through a
+      # `%a{rigor:v1:hkt_define: ...body=...}` annotation.
+      JSON_VALUE_BODY = "nil | true | false | Integer | Float | String | " \
+                        "Array[App[json::value, K]] | Hash[K, App[json::value, K]]"
+      private_constant :JSON_VALUE_BODY
+
+      def json_value_body_tree
+        Rigor::Inference::HktBodyParser.parse(JSON_VALUE_BODY, params: [:K])
+      end
+
+      # `csv::parsed[K]` — `Array[Array[K | nil]]` (CSV.parse's
+      # no-headers shape: an Array of rows; each row is an
+      # Array of optionally-nil cell values). When
+      # `headers: true` the runtime returns a `CSV::Table` /
+      # `CSV::Row` shape instead — that case is NOT covered
+      # by the bundled override (CSV::Row is its own class
+      # with Hash + Array access; a future slice may add a
+      # separate URI or a discriminator hook for it).
+      CSV_PARSED_BODY = "Array[Array[K | nil]]"
+      private_constant :CSV_PARSED_BODY
+
+      def csv_parsed_body_tree
+        Rigor::Inference::HktBodyParser.parse(CSV_PARSED_BODY, params: [:K])
+      end
+
+      def json_value_registration
+        Rigor::Inference::HktRegistry::Registration.new(
+          uri: :"json::value",
+          arity: 1,
+          variance: [:out],
+          bound: Rigor::Type::Combinator.untyped
+        )
+      end
+
+      def json_value_definition
+        Rigor::Inference::HktRegistry.definition_with_body_tree(
+          uri: :"json::value",
+          params: [:K],
+          body_tree: json_value_body_tree,
+          source_path: __FILE__,
+          source_line: __LINE__ - 5
+        )
+      end
+
+      def csv_parsed_registration
+        Rigor::Inference::HktRegistry::Registration.new(
+          uri: :"csv::parsed",
+          arity: 1,
+          variance: [:out],
+          bound: Rigor::Type::Combinator.untyped
+        )
+      end
+
+      def csv_parsed_definition
+        Rigor::Inference::HktRegistry.definition_with_body_tree(
+          uri: :"csv::parsed",
+          params: [:K],
+          body_tree: csv_parsed_body_tree,
+          source_path: __FILE__,
+          source_line: __LINE__ - 5
+        )
+      end
+
+      # @return [Rigor::Inference::HktRegistry] frozen registry
+      #   pre-seeded with all bundled HKT registrations +
+      #   bodies. Allocated fresh each call rather than
+      #   memoised — memoisation through a module-level
+      #   `@registry` ivar surfaces a `Ractor::IsolationError`
+      #   in pool workers (the ivar's contents include
+      #   `HktBody::AppRef` Symbol-keyed structures that the
+      #   current Ractor shareability audit hasn't yet been
+      #   walked through). The registry is small enough that
+      #   per-Environment construction is acceptable; an
+      #   eager-frozen constant is a future optimisation
+      #   once ADR-15 phase 4b.x covers the dependency graph.
+      def registry
+        Rigor::Inference::HktRegistry.new(
+          registrations: [json_value_registration, csv_parsed_registration],
+          definitions: [json_value_definition, csv_parsed_definition]
+        )
+      end
+
+      # ADR-20 slice 3 — hardcoded `(class_name, method_name,
+      # kind) => HKT application` table consulted by the
+      # dispatcher's new HKT-builtin tier. Sits ABOVE
+      # `RbsDispatch.try_dispatch` so a known stdlib method
+      # (`JSON.parse`, `JSON.parse!`) gets the reduced HKT
+      # type instead of the upstream rbs gem's `untyped`
+      # return. The annotation-based `%a{rigor:v1:return:
+      # App[...]}` path (parsed by
+      # `RbsExtended.parse_return_type_override`) is the
+      # general extension surface for user-authored sigs;
+      # this table is the Rigor-bundled shortcut for the
+      # handful of stdlib methods whose RBS declarations
+      # cannot be cleanly overridden via RBS overlay merging.
+      #
+      # Each entry maps to a hash with `:uri` and `:args`
+      # (an array of Ruby class names). The dispatcher
+      # builds `Type::App.new(uri, args.map { Nominal })`,
+      # then reduces via the env's `hkt_registry` so the
+      # caller observes the unfolded form
+      # (`Union[nil, true, false, ..., Array[App[json::value,
+      # String]], Hash[String, App[json::value, String]]]`)
+      # rather than the opaque carrier.
+      JSON_VALUE_SPEC = {
+        uri: :"json::value",
+        args: ["String"],
+        discriminator: :json_symbolize_names,
+        post_reduce: nil
+      }.freeze
+      private_constant :JSON_VALUE_SPEC
+
+      # YAML / Psych.safe_load reuse the json::value reducer
+      # for the JSON-equivalent leaf set BUT additionally
+      # honour `permitted_classes: [<Class>, ...]` literal
+      # Array arguments, unioning each permitted class as an
+      # extra arm of the result. Slice 2c-bis behaviour.
+      YAML_SAFE_VALUE_SPEC = {
+        uri: :"json::value",
+        args: ["String"],
+        discriminator: :json_symbolize_names,
+        post_reduce: :yaml_permitted_classes
+      }.freeze
+      private_constant :YAML_SAFE_VALUE_SPEC
+
+      CSV_PARSED_SPEC = {
+        uri: :"csv::parsed",
+        args: ["String"],
+        discriminator: nil,
+        post_reduce: nil
+      }.freeze
+      private_constant :CSV_PARSED_SPEC
+
+      METHOD_RETURN_OVERRIDES = {
+        # JSON — stdlib's `json` library. Upstream rbs declares
+        # `(string, ?options) -> untyped`; the HKT-builtin tier
+        # tightens to the recursive `json::value[K]` union.
+        # `load_file` / `load_file!` share the `?options` slot
+        # so the `symbolize_names: true` discriminator applies
+        # to them too (just like `parse` / `load`).
+        ["JSON", :parse,      :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :parse!,     :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load,       :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load_file,  :singleton] => JSON_VALUE_SPEC,
+        ["JSON", :load_file!, :singleton] => JSON_VALUE_SPEC,
+        # YAML.safe_load / Psych.safe_load — default
+        # `permitted_classes: []` admits exactly the JSON
+        # vocabulary (nil / true / false / Integer / Float /
+        # String / Array / Hash), so the json::value tree
+        # also describes them. When the call passes a literal
+        # `permitted_classes: [Date, Symbol, ...]` Array, the
+        # `:yaml_permitted_classes` post_reduce unions each
+        # named class into the result. Non-literal options
+        # (a variable, a constant reference, a `+ classes`
+        # concat) silently no-op and the caller observes the
+        # base json::value envelope only. YAML.load /
+        # YAML.unsafe_load deliberately stay out of the
+        # override table — they can return ANY Ruby object
+        # and have no useful HKT envelope.
+        ["YAML",  :safe_load,      :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["YAML",  :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["Psych", :safe_load,      :singleton] => YAML_SAFE_VALUE_SPEC,
+        ["Psych", :safe_load_file, :singleton] => YAML_SAFE_VALUE_SPEC,
+        # CSV.parse / CSV.read — no-headers shape only.
+        # Upstream rbs declares broader return shapes but
+        # the common case is `Array[Array[String?]]` which
+        # the `csv::parsed[String]` URI matches. The
+        # `headers: true` shape (`CSV::Table` of `CSV::Row`)
+        # is NOT covered — calls passing the option fall
+        # through to the upstream RBS type. CSV.foreach also
+        # falls through (it yields rows rather than
+        # returning a typed structure).
+        ["CSV", :parse, :singleton] => CSV_PARSED_SPEC,
+        ["CSV", :read,  :singleton] => CSV_PARSED_SPEC
+      }.freeze
+
+      # @return [Rigor::Type, nil] the reduced HKT type for
+      #   the given (class_name, method_name, kind) triple,
+      #   or `nil` when no built-in override is registered.
+      #   When `arg_types` is supplied AND the entry carries a
+      #   `:discriminator` symbol, the discriminator may swap
+      #   the spec's default args for an alternate (e.g.
+      #   `JSON.parse(str, symbolize_names: true)` discriminates
+      #   `K = Symbol` instead of the default `K = String`).
+      def method_return_override(class_name:, method_name:, kind:, arg_types: nil, hkt_registry: nil)
+        spec = METHOD_RETURN_OVERRIDES[[class_name, method_name.to_sym, kind]]
+        return nil unless spec
+
+        args = discriminated_args(spec, arg_types)
+        registration = hkt_registry&.registration(spec[:uri])
+        bound = registration&.bound || Rigor::Type::Combinator.untyped
+        app = Rigor::Type::App.new(spec[:uri], args, bound: bound)
+
+        reduced =
+          if hkt_registry.nil? || !hkt_registry.defined?(spec[:uri])
+            app
+          else
+            hkt_registry.reduce(app) || app
+          end
+
+        apply_post_reduce(spec[:post_reduce], reduced, arg_types)
+      end
+
+      # Per-spec discriminator dispatch. Slice 3 ships one
+      # built-in discriminator (`json_symbolize_names`) that
+      # observes the optional 2nd argument's `HashShape` for a
+      # literal `symbolize_names: true` entry. Plugin / Rigor-
+      # bundled callers wanting their own discriminators add a
+      # branch here.
+      def discriminated_args(spec, arg_types)
+        default_args = spec[:args].map { |n| Rigor::Type::Nominal.new(n) }
+        return default_args if arg_types.nil?
+        return default_args unless spec[:discriminator] == :json_symbolize_names
+        return default_args unless json_symbolize_names?(arg_types)
+
+        [Rigor::Type::Nominal.new("Symbol")]
+      end
+
+      # Returns true iff the call-site's 2nd argument is a
+      # `Type::HashShape` carrying a literal
+      # `symbolize_names: true` entry. Anything else
+      # (no second arg, non-HashShape, missing key, non-literal
+      # `true`) returns false so the default `K = String`
+      # branch wins.
+      def json_symbolize_names?(arg_types)
+        return false unless arg_types.is_a?(Array) && arg_types.size >= 2
+
+        opts = arg_types[1]
+        return false unless opts.is_a?(Rigor::Type::HashShape)
+
+        value = opts.pairs[:symbolize_names] || opts.pairs["symbolize_names"]
+        value.is_a?(Rigor::Type::Constant) && value.value == true
+      end
+
+      # Slice 2c-bis — post-reduce hook. Receives the already-
+      # reduced `Type` and the call-site's `arg_types`; returns
+      # a (possibly augmented) `Type`. `kind = nil` is the
+      # identity (passes the reduced type through unchanged).
+      # Only `:yaml_permitted_classes` is implemented today;
+      # plugin / Rigor-bundled callers wanting their own
+      # post-reduce hooks add a branch here.
+      def apply_post_reduce(kind, reduced, arg_types)
+        case kind
+        when :yaml_permitted_classes
+          augment_with_yaml_permitted_classes(reduced, arg_types)
+        else
+          # `nil` (no post-reduce declared) and any future
+          # unrecognised kind both pass the reduced type
+          # through unchanged. Unknown kinds are silently
+          # tolerated rather than raised because adding a
+          # new kind on a Rigor upgrade should not crash a
+          # stale METHOD_RETURN_OVERRIDES entry on the
+          # caller side.
+          reduced
+        end
+      end
+
+      # Inspects arg_types for a `permitted_classes: [<Class>,
+      # ...]` literal Array in the options Hash and unions
+      # each named class into the reduced result. Non-literal
+      # `permitted_classes:` values (a variable, a constant
+      # reference, a concat) silently no-op and the caller
+      # observes the base json::value envelope only. Defensive
+      # against the various ways Ruby literal arrays surface
+      # as Rigor types: `Tuple[Singleton<Date>]` for a single
+      # element, `Tuple[Singleton<Date>, Singleton<Symbol>]`
+      # for multiple, `Nominal[Array, [Singleton<...>]]` if
+      # the analyzer widened (rare for literal arrays).
+      def augment_with_yaml_permitted_classes(reduced, arg_types)
+        return reduced unless arg_types.is_a?(Array) && arg_types.size >= 2
+
+        opts = arg_types[1]
+        return reduced unless opts.is_a?(Rigor::Type::HashShape)
+
+        value = opts.pairs[:permitted_classes] || opts.pairs["permitted_classes"]
+        return reduced if value.nil?
+
+        extras = permitted_class_nominals(value)
+        return reduced if extras.empty?
+
+        Rigor::Type::Combinator.union(reduced, *extras)
+      end
+
+      # Extract Singleton-class elements from a Tuple or
+      # Array-shape carrier, mapping each to its Nominal
+      # counterpart. Returns an empty array when no static
+      # Singletons are reachable (e.g. value is `Dynamic[T]`,
+      # element types are non-Singleton, etc.).
+      def permitted_class_nominals(value)
+        candidates =
+          if value.is_a?(Rigor::Type::Tuple)
+            value.elements
+          elsif value.is_a?(Rigor::Type::Nominal) && value.class_name == "Array" && value.type_args.size == 1
+            element = value.type_args.first
+            element.is_a?(Rigor::Type::Union) ? element.members : [element]
+          else
+            []
+          end
+
+        candidates.filter_map do |c|
+          c.is_a?(Rigor::Type::Singleton) ? Rigor::Type::Nominal.new(c.class_name) : nil
+        end
+      end
+    end
+  end
+end

data/lib/rigor/builtins/imported_refinements.rb

@@ -419,9 +419,13 @@ module Rigor
           elsif (literal = @scanner.scan(SIGNED_INT))
             TypeNode::IntegerLiteral.new(value: Integer(literal))
           elsif @scanner.scan(SYMBOL_LITERAL)
-            TypeNode::SymbolLiteral.new(value: @scanner[:value].to_sym)
+            # StringScanner#[] accepts Symbol for named captures
+            # (Ruby behaviour); upstream RBS shim only declares the
+            # positional-capture (Integer) overload, so the
+            # argument-type-mismatch diagnostic is suppressed.
+            TypeNode::SymbolLiteral.new(value: @scanner[:value].to_sym) # rigor:disable argument-type-mismatch
           elsif @scanner.scan(STRING_LITERAL)
-            TypeNode::StringLiteral.new(value: @scanner[:value])
+            TypeNode::StringLiteral.new(value: @scanner[:value]) # rigor:disable argument-type-mismatch
           else
             parse_type_ast
           end