rigortype 0.1.19 → 0.2.0

data/lib/rigor/inference/method_dispatcher/struct_folding.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+require_relative "singleton_folding"
+require_relative "member_shape_projection"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # ADR-48 Struct follow-up — `Struct.new` value folding, the mutable
+      # sibling of {DataFolding}. Same fully-decidable-shape, degrade-on-any-
+      # uncertainty discipline, with one extra premise the immutable `Data`
+      # path does not need: **mutation soundness.**
+      #
+      # A `Struct` instance is mutable (`s.x = v`, `s[:x] = v`, escape), so a
+      # member map bound to a variable can be invalidated by a later write.
+      # This slice (ADR-48 slices 1+2 in the sound *transient* form) folds a
+      # member read ONLY off a **fresh** instance — the transient receiver of
+      # a `.new(...).x` / `.with(...).x` chain, which provably cannot have
+      # been mutated between materialisation and the read. A member read off
+      # a *stored* binding degrades to `Dynamic[top]` rather than fold a
+      # possibly-stale value. Promoting the fold to mutation-free bound
+      # locals is the deferred slice 3 (relax the fresh-receiver gate to a
+      # fold-safe-local scan); precise mutated-member re-typing is slice 4.
+      #
+      # Responsibilities:
+      #
+      # 1. `Struct.new(:x, :y [, keyword_init: <bool>])` on a
+      #    `Singleton[Struct]` receiver, literal-Symbol members, NO block ->
+      #    `StructClass{members:, keyword_init:}`. A block / non-literal
+      #    members defer.
+      # 2. `.new` / `.[]` on a `StructClass` (or a `Singleton[Point]` with a
+      #    recorded struct layout) -> a `StructInstance`, the member map built
+      #    from the call's arguments (positional or keyword per the class's
+      #    `keyword_init`). A form / arity mismatch degrades to `Dynamic[top]`
+      #    rather than a wrong member map. `.members` on the class folds.
+      # 3. member reads + `[]` / `to_h` / `deconstruct` / `deconstruct_keys`
+      #    / `members` / `with` on a *fresh* `StructInstance` -> the precise
+      #    projected type; member *setters* (`s.x = v`) return the assigned
+      #    value type. Unhandled / stored-receiver calls return nil so the
+      #    pipeline projects the instance to its nominal through RbsDispatch.
+      #
+      # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+      module StructFolding
+        module_function
+
+        # The `[]` / `to_h` / `deconstruct` / `members` / `with` projections
+        # and the reader-redefinition guard are shared with {DataFolding}.
+        extend MemberShapeProjection
+
+        # @return [Rigor::Type, nil] the folded result, or nil to defer.
+        def try_dispatch(context)
+          receiver = context.receiver
+
+          return fold_struct_new(context) if SingletonFolding.receiver?(receiver, "Struct")
+
+          case receiver
+          when Type::StructClass
+            dispatch_struct_class(receiver, context)
+          when Type::StructInstance
+            fold_instance(receiver, context)
+          when Type::Singleton
+            fold_named_new(receiver, context)
+          end
+        end
+
+        # A `Struct.new`-defined class assigned to a constant (or a
+        # `class Point < Struct.new(...)` subclass) is canonicalised by the
+        # engine to `Singleton[Point]`, not a `StructClass` — so its member
+        # layout is read from the project side-table the scope indexer built
+        # (`Scope#struct_member_layout`) rather than from the receiver
+        # carrier.
+        def fold_named_new(singleton, context)
+          scope = context.scope
+          return nil if scope.nil?
+
+          layout = scope.struct_member_layout(singleton.class_name)
+          return nil if layout.nil?
+
+          materialize_instance(layout[:members], layout[:keyword_init], singleton.class_name, context)
+        end
+
+        # --- 1. Struct.new(:x, :y) --------------------------------------
+
+        def fold_struct_new(context)
+          return nil unless context.method_name == :new
+          # Block-form (`Struct.new(:x) do ... end`) defers — the named
+          # constant/subclass forms still fold via the layout side-table.
+          return nil unless context.block_type.nil?
+
+          parsed = parse_struct_new_args(context.args)
+          return nil if parsed.nil?
+
+          Type::Combinator.struct_class_of(members: parsed[:members], keyword_init: parsed[:keyword_init])
+        end
+
+        # Parses `Struct.new`'s arguments into `{ members:, keyword_init: }`,
+        # or nil when any argument is non-conforming (a dynamic member name,
+        # an unexpected trailing keyword). Handles the optional leading String
+        # class name and the trailing `keyword_init:` option hash.
+        def parse_struct_new_args(args)
+          rest = args.dup
+          keyword_init = false
+
+          if rest.last.is_a?(Type::HashShape)
+            options = rest.pop
+            return nil unless struct_options_hash?(options)
+
+            value = options.pairs[:keyword_init]
+            keyword_init = value.is_a?(Type::Constant) && value.value == true
+          end
+
+          # Optional leading String name: `Struct.new("Point", :x, :y)`.
+          rest = rest[1..] if rest.first.is_a?(Type::Constant) && rest.first.value.is_a?(String)
+
+          members = []
+          rest.each do |arg|
+            return nil unless arg.is_a?(Type::Constant) && arg.value.is_a?(Symbol)
+
+            members << arg.value
+          end
+          return nil if members.empty?
+          return nil unless members.uniq.size == members.size
+
+          { members: members, keyword_init: keyword_init }
+        end
+
+        # A trailing hash is the `Struct.new` options hash only when it is a
+        # closed shape whose sole key is `:keyword_init`. Any other key means
+        # the call is not a recognisable member-list definition -> defer.
+        def struct_options_hash?(shape)
+          shape.closed? && shape.optional_keys.empty? &&
+            shape.pairs.keys.all? { |key| key == :keyword_init }
+        end
+
+        # --- 2. Point.new(...) / Point[...] / Point.members -------------
+
+        def dispatch_struct_class(struct_class, context)
+          case context.method_name
+          when :new, :[]
+            materialize_instance(struct_class.members, struct_class.keyword_init,
+                                 struct_class.class_name, context)
+          when :members
+            Type::Combinator.tuple_of(*struct_class.members.map { |name| Type::Combinator.constant_of(name) })
+          end
+        end
+
+        def materialize_instance(members, keyword_init, class_name, context)
+          return nil unless %i[new []].include?(context.method_name)
+
+          map = member_map_for_new(members, keyword_init, context)
+          return degraded_instance if map.nil?
+
+          Type::Combinator.struct_instance_of(members: map, class_name: class_name)
+        end
+
+        # Builds the member -> type map honouring the class's `keyword_init`
+        # flag: a `keyword_init: true` struct accepts only the keyword form,
+        # a positional struct only the positional form. The mismatched form
+        # is a different runtime shape, so it degrades rather than fold.
+        def member_map_for_new(members, keyword_init, context)
+          if keyword_new?(context)
+            keyword_init ? keyword_member_map(members, context.args) : nil
+          else
+            keyword_init ? nil : positional_member_map(members, context.args)
+          end
+        end
+
+        # `Point.new(x: 1)` arrives as a single trailing `HashShape` whose
+        # call node is a `KeywordHashNode`; distinguishing it from a
+        # positional hash needs the call node (both type to a `HashShape`).
+        def keyword_new?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          arguments = node.arguments&.arguments
+          return false if arguments.nil? || arguments.empty?
+
+          arguments.last.is_a?(Prism::KeywordHashNode)
+        end
+
+        # `Struct.new(:a, :b).new(v)` is legal — trailing members default to
+        # `nil` — so fewer positionals than members pad with `Constant[nil]`;
+        # more positionals than members is an ArgumentError -> degrade.
+        def positional_member_map(members, args)
+          return nil if args.size > members.size
+
+          members.each_with_index.to_h do |name, index|
+            [name, index < args.size ? args[index] : Type::Combinator.constant_of(nil)]
+          end
+        end
+
+        # `Struct.new(:a, :b).new(a: 1)` is legal — omitted members default
+        # to `nil` — so a keyword subset pads the rest; an unknown key is an
+        # ArgumentError -> degrade.
+        def keyword_member_map(members, args)
+          return nil unless args.size == 1
+
+          shape = args.first
+          return nil unless shape.is_a?(Type::HashShape) && shape.closed?
+          return nil unless shape.optional_keys.empty?
+          return nil unless shape.pairs.keys.all? { |key| members.include?(key) }
+
+          members.to_h { |name| [name, shape.pairs[name] || Type::Combinator.constant_of(nil)] }
+        end
+
+        # A `.new` whose arguments cannot soundly populate the member map
+        # degrades to `Dynamic[top]` (today's behaviour for `Struct.new(...)`
+        # instances), never a wrong map.
+        def degraded_instance
+          Type::Combinator.untyped
+        end
+
+        # --- 3. inst.x / inst.x = v / inst[...] / inst.to_h / ... -------
+
+        def fold_instance(instance, context)
+          method_name = context.method_name
+          args = context.args
+          members = instance.members
+
+          # Member setter `s.x = v`: returns the assigned value type. Sound
+          # regardless of mutation state (it models the setter's own return),
+          # and avoids a fall-through undefined-method on a writer the
+          # existence table does not register.
+          setter = member_setter_target(method_name, members)
+          return args.first if setter && args.size == 1
+
+          foldable = foldable_receiver?(context)
+
+          if members.key?(method_name) && args.empty? && !reader_overridden?(instance, method_name, context.scope)
+            # A stored receiver folds only when the bound local is proven
+            # fold-safe (ADR-48 slice 3 — never mutated / aliased / escaped);
+            # otherwise the member value may be stale, so it degrades to
+            # `Dynamic[top]` (not nil -> no undefined-method fall-through).
+            return foldable ? members.fetch(method_name) : Type::Combinator.untyped
+          end
+
+          # Projections fold only off a foldable (fresh, or proven fold-safe)
+          # instance; off any other stored binding they defer to Struct's RBS
+          # (`to_h` / `[]` / `members` / `deconstruct*` all exist on `Struct`),
+          # which is sound and non-regressive.
+          return nil unless foldable
+
+          fold_fresh_projection(instance, method_name, args)
+        end
+
+        def fold_fresh_projection(instance, method_name, args)
+          case method_name
+          when :[] then instance_index(instance, args)
+          when :to_h, :to_hash then instance_to_h(instance)
+          when :deconstruct then instance_deconstruct(instance)
+          when :deconstruct_keys then instance_deconstruct_keys(instance, args)
+          when :members then instance_members(instance)
+          when :with
+            instance_with(instance, args) do |members, class_name|
+              Type::Combinator.struct_instance_of(members: members, class_name: class_name)
+            end
+          end
+        end
+
+        # The member name a `:<member>=` setter targets, or nil. Comparison
+        # operators (`==`, `>=`, ...) end with `=` too but never strip to a
+        # member symbol, so they fall through to the normal dispatch path.
+        def member_setter_target(method_name, members)
+          name = method_name.to_s
+          return nil unless name.end_with?("=")
+
+          base = name[0..-2].to_sym
+          members.key?(base) ? base : nil
+        end
+
+        # A member read is foldable when the receiver is either FRESH (the
+        # transient result of a `.new(...)`/`.with(...)` chain, which cannot
+        # have been mutated between materialisation and this read) or a
+        # FOLD-SAFE stored local (ADR-48 slice 3 — `StructFoldSafety` proved
+        # the binding is never mutated / aliased / escaped in its scope).
+        def foldable_receiver?(context)
+          fresh_receiver?(context) || fold_safe_local_receiver?(context)
+        end
+
+        # A fresh receiver is the transient result of a chained call
+        # (`Point.new(1, 2).x`, `inst.with(x: 9).y`).
+        def fresh_receiver?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          node.receiver.is_a?(Prism::CallNode)
+        end
+
+        # A fold-safe stored receiver is a local-variable read whose name the
+        # body's fold-safe set (on the scope) marks as never mutated.
+        def fold_safe_local_receiver?(context)
+          node = context.call_node
+          receiver = node&.receiver
+          scope = context.scope
+          return false unless receiver.is_a?(Prism::LocalVariableReadNode) && scope
+
+          scope.struct_fold_safe?(receiver.name)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher.rb

@@ -12,6 +12,7 @@ require_relative "method_dispatcher/constant_folding"
 require_relative "method_dispatcher/literal_string_folding"
 require_relative "method_dispatcher/shape_dispatch"
 require_relative "method_dispatcher/data_folding"
+require_relative "method_dispatcher/struct_folding"
 require_relative "method_dispatcher/rbs_dispatch"
 require_relative "method_dispatcher/iterator_dispatch"
 require_relative "method_dispatcher/reduce_folding"
@@ -38,28 +39,15 @@ module Rigor
     # callers (today only `ExpressionTyper`) own the fail-soft fallback
     # and decide whether to record a `FallbackTracer` event.
     #
-    # Tiers (in order):
+    # Tier order is documented inline in `resolve`; the precise-tier
+    # group is built from `PRECISE_TIERS_HEAD`, `STDLIB_SINGLETON_FOLDERS`,
+    # and `PRECISE_TIERS_TAIL`. `ShapeDispatch` runs above {RbsDispatch}
+    # so a precise per-position/per-key answer wins over the projected
+    # `Array#[]`/`Hash#fetch` RBS answer.
     #
-    # 1. {ConstantFolding}: executes the Ruby operation directly when
-    #    the receiver and argument are `Constant` carriers and the
-    #    method is on the curated whitelist. Slice 2.
-    # 2. {ShapeDispatch}: returns the precise element/value type for a
-    #    curated catalogue of `Tuple`/`HashShape` element-access
-    #    methods (`first`, `last`, `[]` with a static integer/key,
-    #    `fetch`, `dig`, `size`/`length`/`count`). Slice 5 phase 2.
-    # 3. {RbsDispatch}: looks up the receiver's class in the RBS
-    #    environment carried by the scope and translates the method's
-    #    return type into a Rigor::Type. Slice 4.
-    #
-    # `ShapeDispatch` deliberately runs *above* {RbsDispatch} so the
-    # precise per-position/per-key answer wins over the projected
-    # `Array#[]`/`Hash#fetch` answer; it falls through (`nil`) when
-    # the call cannot be proved against the static shape, in which
-    # case the projection answer from {RbsDispatch} applies.
-    #
-    # The dispatcher's public signature reserves space for `block_type:`
-    # and ADR-2 plugin extensions (later slices), so call sites added
-    # now do not have to be rewritten when those tiers arrive.
+    # The `block_type:` and plugin contribution (`dynamic_return`) tiers
+    # landed in Slice 6 phase C and v0.1.1 Track 2 respectively; all
+    # call sites pass through `dispatch`/`resolve` unchanged.
     module MethodDispatcher # rubocop:disable Metrics/ModuleLength
       module_function
 
@@ -326,19 +314,6 @@ module Rigor
         Type::Combinator.untyped
       end
 
-      # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
-      # slice 7; ADR-52 WD3 — consults each loaded plugin's gated
-      # `dynamic_return` rules, wraps the contributed types as
-      # `FlowContribution` bundles, merges them through
-      # `FlowContribution::Merger`, and returns the merged
-      # `return_type` slot (or nil when no plugin contributed a
-      # return type).
-      #
-      # Plugins whose hook raises have their contribution
-      # silently dropped for this call so the dispatch chain
-      # keeps moving — the run-level diagnostic envelope (per
-      # ADR-2 § "Plugin Trust and I/O Policy") is owned by
-      # `Analysis::Runner#plugin_emitted_diagnostics`.
       # ADR-20 slice 3 — looks up the receiver / method pair
       # in {Rigor::Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES}
       # and returns the reduced HKT type. Only fires when the
@@ -413,6 +388,19 @@ module Rigor
         end
       end
 
+      # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
+      # slice 7; ADR-52 WD3 — consults each loaded plugin's gated
+      # `dynamic_return` rules, wraps the contributed types as
+      # `FlowContribution` bundles, merges them through
+      # `FlowContribution::Merger`, and returns the merged
+      # `return_type` slot (or nil when no plugin contributed a
+      # return type).
+      #
+      # Plugins whose hook raises have their contribution
+      # silently dropped for this call so the dispatch chain
+      # keeps moving — the run-level diagnostic envelope (per
+      # ADR-2 § "Plugin Trust and I/O Policy") is owned by
+      # `Analysis::Runner#plugin_emitted_diagnostics`.
       def try_plugin_contribution(call_node, scope, receiver_type)
         return nil if call_node.nil? || scope.nil?
 
@@ -425,16 +413,6 @@ module Rigor
         FlowContribution::Merger.merge(contributions).return_type
       end
 
-      # ADR-10 slice 2b-ii. Consults the per-run
-      # `Analysis::DependencySourceInference::Index` carried by
-      # the environment for `(class_name, method_name)`
-      # observations harvested from opt-in gems' `roots:`. On a
-      # hit, returns `Combinator.untyped` so the call site
-      # carries the `Dynamic[top]` provenance (per ADR-10's
-      # "Inference contract": gem-source-inferred shapes never
-      # publish as ground-truth `T`). Returns `nil` when the
-      # environment carries no index, the index has no entry, or
-      # the receiver has no nominal class to look up.
       # ADR-16 synthetic-method tier. Slice 2b shipped the floor —
       # a match short-circuits at the right precedence (above
       # dep-source / discovered / user-class-fallback; below RBS)
@@ -556,6 +534,16 @@ module Rigor
         Type::Combinator.dynamic(entry.return_type)
       end
 
+      # ADR-10 slice 2b-ii. Consults the per-run
+      # `Analysis::DependencySourceInference::Index` carried by
+      # the environment for `(class_name, method_name)`
+      # observations harvested from opt-in gems' `roots:`. On a
+      # hit, returns `Combinator.untyped` so the call site
+      # carries the `Dynamic[top]` provenance (per ADR-10's
+      # "Inference contract": gem-source-inferred shapes never
+      # publish as ground-truth `T`). Returns `nil` when the
+      # environment carries no index, the index has no entry, or
+      # the receiver has no nominal class to look up.
       def try_dependency_source(receiver_type, method_name, environment)
         index = environment&.dependency_source_index
         return nil if index.nil? || index.empty?
@@ -759,10 +747,6 @@ module Rigor
       # below this chain and is invoked by the outer `dispatch`
       # method.
       #
-      # `BlockFolding` runs last among the precision tiers because
-      # its rules apply only to block-taking calls, so the cheaper
-      # arity-based fold tiers above it filter out the common
-      # cases first. When `block_type` is nil the tier is a no-op.
       # The precise-tier folders, consulted in order via the uniform
       # `_DispatchTier` interface (`try_dispatch(CallContext) -> Type?`).
       # Order is significant: ConstantFolding's exact-value folds win
@@ -815,6 +799,14 @@ module Rigor
         data_result = DataFolding.try_dispatch(context)
         return data_result if data_result
 
+        # ADR-48 Struct follow-up — runs in the same band and for the same
+        # reason as DataFolding: `meta_new` would otherwise intercept every
+        # `Singleton[*].new` (the old `struct_new_lift` produced a bare
+        # `Singleton[Struct]`), masking a Struct class's precise instance.
+        # Only fires on Struct receivers, so it never shadows meta's lifts.
+        struct_result = StructFolding.try_dispatch(context)
+        return struct_result if struct_result
+
         meta_result = try_meta_introspection(context.receiver, context.method_name, context.args)
         return meta_result if meta_result
 

data/lib/rigor/inference/mutation_widening.rb

@@ -67,18 +67,12 @@ module Rigor
     #   ...; @warning_issued = true`). Requires tracking the
     #   first-write position; flow-sensitive but orthogonal.
     # - **Local-variable mutation inside a block body** (e.g.
-    #   `arr = []; xs.each { |x| arr << x }`). Block bodies
-    #   create a child scope; the existing closure-escape model
-    #   only widens outer locals when the block ESCAPES the
-    #   call. An in-place mutator inside a non-escaping block on
-    #   an outer LOCAL does not yet flow back. **Ivar mutations
-    #   inside a block ARE handled** (ivars live in the
-    #   method-body scope, not the block-local scope) — the
-    #   widening fires from inside the block and the new ivar
-    #   binding is visible to the outer scope.
+    #   `arr = []; xs.each { |x| arr << x }`) — landed as
+    #   ADR-56 slice A (`widen_after_block`). **Ivar mutations
+    #   inside a block ARE also handled** (ivars live in the
+    #   method-body scope, not the block-local scope).
     #
-    # Those four are documented as "G2 remaining" in
-    # `docs/CURRENT_WORK.md` and are intentionally deferred.
+    # The remaining three items above are demand-gated; see ADR-56.
     module MutationWidening
       # Array mutators that change either the size or the element
       # set of a literal-shape carrier (Tuple). Receiver-mutating

data/lib/rigor/inference/narrowing.rb

@@ -11,7 +11,8 @@ require_relative "../builtins/regex_refinement"
 
 module Rigor
   module Inference
-    # Slice 6 phase 1 minimal narrowing surface.
+    # Control-flow predicate narrowing and type-lattice narrowing
+    # primitives.
     #
     # `Rigor::Inference::Narrowing` answers two related questions:
     #
@@ -19,22 +20,19 @@ module Rigor
     #    truthy fragment, its falsey fragment, its nil fragment, and its
     #    non-nil fragment? These primitives understand the value-lattice
     #    algebra (`Constant`, `Nominal`, `Singleton`, `Tuple`, `HashShape`,
-    #    `Union`) and stay conservative on `Top` and `Dynamic[T]`, where
-    #    the analyzer cannot prove the boundary either way.
+    #    `Union`) and stay conservative on `Top` and `Dynamic[T]`.
     # 2. Predicate-level narrowing: given a Prism predicate node and an
     #    entry scope, what are the truthy-edge scope and the falsey-edge
-    #    scope after the predicate has been evaluated? The phase 1
-    #    catalogue covers truthiness on `LocalVariableReadNode`, `nil?`
-    #    against a local, the unary `!` inverter, parenthesised
-    #    predicates, and short-circuiting `&&` / `||` chains.
+    #    scope? The catalogue covers truthiness, `nil?`, `!`, `&&`/`||`,
+    #    class-membership (`is_a?`, `kind_of?`, `instance_of?`), trusted
+    #    equality/inequality against static literals, `case`/`when`,
+    #    regex match globals, string predicates (`start_with?` etc.),
+    #    key-presence, array emptiness, numeric comparison, and
+    #    `respond_to?`.
     #
-    # Predicate-level narrowing is consumed by
-    # `Rigor::Inference::StatementEvaluator` to refine the `then` and
-    # `else` scopes of `IfNode`/`UnlessNode`. Phase 1 narrows local
-    # bindings on truthiness and `nil?`; phase 2 extends the catalogue
-    # with class-membership predicates (`is_a?`, `kind_of?`,
-    # `instance_of?`) and trusted equality/inequality checks against
-    # static literals.
+    # Consumed by `Rigor::Inference::StatementEvaluator` to refine
+    # `then`/`else` scopes of `IfNode`/`UnlessNode` and
+    # `case`/`when` branches.
     #
     # The module is pure: every public function returns fresh values and
     # MUST NOT mutate its inputs. Unrecognised predicate shapes degrade
@@ -43,8 +41,8 @@ module Rigor
     # `[truthy_scope, falsey_scope]` pair (the entry scope twice when no
     # rule matches).
     #
-    # See docs/internal-spec/inference-engine.md (Slice 6 — Narrowing)
-    # and docs/type-specification/control-flow-analysis.md for the
+    # See docs/internal-spec/inference-engine.md (Narrowing) and
+    # docs/type-specification/control-flow-analysis.md for the
     # binding contract.
     # rubocop:disable Metrics/ModuleLength
     module Narrowing