rigortype 0.1.15 → 0.1.16

data/lib/rigor/inference/synthetic_method_index.rb

@@ -29,9 +29,19 @@ module Rigor
     # floor — the recorded string is the input to a later slice's
     # precision promotion via ADR-13's `Plugin::TypeNodeResolver`.
     class SyntheticMethodIndex
-      attr_reader :entries
+      attr_reader :entries, :class_names
 
-      def initialize(entries: [])
+      # @param entries [Array<SyntheticMethod>]
+      # @param class_names [Array<String>, Set<String>] names of
+      #   classes the substrate synthesises wholesale (ADR-36
+      #   nested-class emission — the variant subclasses that have
+      #   no RBS/source declaration of their own). Recorded so
+      #   `Environment#class_known?` can resolve them as classes
+      #   (their constant reference + `.new` dispatch) even though
+      #   nothing else in the type universe declares them. Tier B/C
+      #   method emissions leave this empty (their receiver classes
+      #   are already real).
+      def initialize(entries: [], class_names: [])
         unless entries.is_a?(Array) && entries.all?(SyntheticMethod)
           raise ArgumentError,
                 "SyntheticMethodIndex#entries must be an Array of SyntheticMethod, got #{entries.inspect}"
@@ -40,11 +50,20 @@ module Rigor
         @entries = Ractor.make_shareable(entries.dup)
         @by_instance = Ractor.make_shareable(bucket(entries, SyntheticMethod::INSTANCE))
         @by_singleton = Ractor.make_shareable(bucket(entries, SyntheticMethod::SINGLETON))
+        @class_names = Ractor.make_shareable(class_names.to_a.map(&:to_s).uniq.freeze)
+        @class_name_set = Ractor.make_shareable(@class_names.to_set)
         freeze
       end
 
       def empty?
-        entries.empty?
+        entries.empty? && class_names.empty?
+      end
+
+      # True when `name` is a substrate-synthesised class (an
+      # ADR-36 variant subclass). Used by `Environment#class_known?`
+      # so the constant resolves and `.new` dispatches.
+      def knows_class?(name)
+        @class_name_set.include?(name.to_s)
       end
 
       # Returns an Array of matching {SyntheticMethod} records in
@@ -59,7 +78,7 @@ module Rigor
       end
 
       def to_h
-        { "entries" => entries.map(&:to_h) }
+        { "entries" => entries.map(&:to_h), "class_names" => class_names }
       end
 
       EMPTY_ROW = [].freeze

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../plugin/macro/heredoc_template"
 require_relative "../plugin/macro/trait_registry"
+require_relative "../source/literals"
 require_relative "synthetic_method"
 require_relative "synthetic_method_index"
 
@@ -69,13 +70,15 @@ module Rigor
       def scan(plugin_registry:, paths:, environment: nil, fact_store: nil, buffer: nil)
         templates = collect_templates(plugin_registry)
         registries = collect_trait_registries(plugin_registry)
-        return SyntheticMethodIndex::EMPTY if templates.empty? && registries.empty?
+        nested_templates = collect_nested_class_templates(plugin_registry)
+        return SyntheticMethodIndex::EMPTY if templates.empty? && registries.empty? && nested_templates.empty?
 
         asts = parse_paths(paths, buffer: buffer)
         hierarchy = build_hierarchy(asts)
         concern_index = build_concern_index(asts)
 
         entries = []
+        class_names = []
         asts.each do |path, ast|
           walk_class_bodies(ast) do |class_name, call_node|
             collect_entries(entries, templates, class_name, call_node, hierarchy, environment, path, fact_store)
@@ -85,9 +88,10 @@ module Rigor
               templates, registries, hierarchy, environment, path, fact_store
             )
           end
+          collect_nested_class_entries(entries, class_names, nested_templates, ast, path) unless nested_templates.empty?
         end
 
-        SyntheticMethodIndex.new(entries: entries)
+        SyntheticMethodIndex.new(entries: entries, class_names: class_names)
       end
 
       # Aggregates `(plugin_id, template)` pairs across every
@@ -119,6 +123,146 @@ module Rigor
         end
       end
 
+      # ADR-36 — aggregates `(plugin_id, template)` pairs across
+      # every plugin's `manifest.nested_class_templates`. Empty when
+      # no plugin contributes the nested-class emission tier.
+      def collect_nested_class_templates(plugin_registry)
+        return [] if plugin_registry.nil? || plugin_registry.empty?
+
+        plugin_registry.plugins.flat_map do |plugin|
+          # rigor:disable undefined-method
+          plugin.manifest.nested_class_templates.map do |template|
+            [plugin.manifest.id, template]
+          end
+        end
+      end
+
+      # ADR-36 nested-class emission. For each class that `extend`s a
+      # template's `receiver_constraint` and carries a
+      # `<block_method> do ... end` block, mint one synthetic
+      # subclass per `<variant_method> <Const>, <Type>` row:
+      #
+      #   class Shape
+      #     extend Mangrove::Enum
+      #     variants do
+      #       variant Circle, Float
+      #     end
+      #   end
+      #
+      # yields synthetic class `Shape::Circle` + instance method
+      # `Shape::Circle#inner -> Float`. The variant subclass name is
+      # recorded in `class_names` so `Environment#class_known?`
+      # resolves the constant (and `.new` dispatches through
+      # `meta_new`); `#inner`'s return type is the literal constant
+      # type argument (non-constant inner shapes degrade to
+      # `Dynamic[Top]` per the slice-A floor).
+      def collect_nested_class_entries(entries, class_names, nested_templates, ast, path)
+        return if ast.nil?
+
+        walk_classes(ast) do |class_name, class_node|
+          body = class_body_statements(class_node)
+          next if body.empty?
+
+          nested_templates.each do |(plugin_id, template)|
+            next unless body_extends?(body, template.receiver_constraint)
+
+            each_variant_call(body, template) do |variant_const, inner_node|
+              emit_variant(entries, class_names, class_name, variant_const, inner_node, template, plugin_id, path)
+            end
+          end
+        end
+      end
+
+      # Walks every class declaration, yielding its fully-qualified
+      # name and the `Prism::ClassNode`. Mirrors `walk_class_bodies`'
+      # scope-stack bookkeeping but hands back the class node itself.
+      def walk_classes(node, scope_stack = [], &)
+        return unless node.respond_to?(:compact_child_nodes)
+
+        case node
+        when Prism::ClassNode
+          name = class_name_from(node, scope_stack)
+          yield name, node if name
+          new_stack = scope_stack + [node]
+          node.body&.compact_child_nodes&.each { |child| walk_classes(child, new_stack, &) }
+        when Prism::ModuleNode
+          new_stack = scope_stack + [node]
+          node.body&.compact_child_nodes&.each { |child| walk_classes(child, new_stack, &) }
+        else
+          node.compact_child_nodes.each { |child| walk_classes(child, scope_stack, &) }
+        end
+      end
+
+      def class_body_statements(class_node)
+        body = class_node.body
+        body.respond_to?(:body) ? body.body.compact : []
+      end
+
+      # True when the class body carries `extend <constraint>`
+      # (receiverless `extend` call with the constraint constant as
+      # its first argument).
+      def body_extends?(body, constraint)
+        body.any? do |stmt|
+          stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :extend &&
+            const_name_string(first_arg(stmt)) == constraint
+        end
+      end
+
+      # Yields `(variant_const_name, inner_type_node)` for every
+      # `<variant_method> <Const>, <Type>` call inside the template's
+      # `<block_method> do ... end` block(s).
+      def each_variant_call(body, template, &)
+        body.each do |stmt|
+          next unless variants_block_call?(stmt, template)
+
+          block_body_statements(stmt.block).each { |call| yield_variant(call, template, &) }
+        end
+      end
+
+      def variants_block_call?(stmt, template)
+        stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? &&
+          stmt.name == template.block_method && stmt.block.is_a?(Prism::BlockNode)
+      end
+
+      def yield_variant(call, template)
+        return unless call.is_a?(Prism::CallNode) && call.receiver.nil? && call.name == template.variant_method
+
+        args = call.arguments&.arguments || []
+        variant_const = const_name_string(args[template.name_arg_position])
+        return if variant_const.nil?
+
+        yield variant_const, args[template.inner_arg_position]
+      end
+
+      def block_body_statements(block_node)
+        body = block_node.body
+        body.respond_to?(:body) ? body.body.compact : []
+      end
+
+      def emit_variant(entries, class_names, enclosing, variant_const, inner_node, template, plugin_id, path) # rubocop:disable Metrics/ParameterLists
+        variant_class = "#{enclosing}::#{variant_const}"
+        class_names << variant_class
+        inner_type = const_name_string(inner_node) || "untyped"
+
+        entries << SyntheticMethod.new(
+          class_name: variant_class,
+          method_name: template.inner_reader,
+          return_type: inner_type,
+          kind: SyntheticMethod::INSTANCE,
+          provenance: {
+            plugin_id: plugin_id,
+            tier: "nested_class",
+            enclosing: enclosing,
+            variant: variant_const,
+            source_path: path
+          }
+        )
+      end
+
+      def first_arg(call_node)
+        call_node.arguments&.arguments&.first
+      end
+
       def parse_paths(paths, buffer: nil)
         paths.to_h do |path|
           physical = buffer ? buffer.resolve(path) : path
@@ -399,9 +543,7 @@ module Rigor
       end
 
       def literal_symbol_value(node)
-        case node
-        when Prism::SymbolNode, Prism::StringNode then node.unescaped.to_sym
-        end
+        Source::Literals.symbol_or_string(node)
       end
 
       def emit_trait_module_entries(entries, class_name, modules, registry, plugin_id, path, call_node, environment) # rubocop:disable Metrics/ParameterLists
@@ -584,15 +726,7 @@ module Rigor
       end
 
       def literal_symbol_arg(call_node, index)
-        args_node = call_node.arguments
-        return nil if args_node.nil?
-
-        arg = args_node.arguments[index]
-        return nil unless arg
-
-        case arg
-        when Prism::SymbolNode, Prism::StringNode then arg.unescaped.to_sym
-        end
+        Source::Literals.symbol_arg(call_node, index)
       end
     end
   end

data/lib/rigor/plugin/additional_initializer.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    # ADR-38 declaration: "on `receiver_constraint` (and its
+    # subclasses), every method named in `methods` also establishes
+    # instance-variable state — treat it like `initialize` for the
+    # read-before-write nil soundness gate."
+    #
+    # Authored on a plugin manifest:
+    #
+    #   manifest(
+    #     id: "minitest",
+    #     version: "0.1.0",
+    #     additional_initializers: [
+    #       Rigor::Plugin::AdditionalInitializer.new(
+    #         receiver_constraint: "Minitest::Test",
+    #         methods: [:setup]
+    #       )
+    #     ]
+    #   )
+    #
+    # The Ruby analogue of PHPStan's `AdditionalConstructorsExtension`.
+    # `Rigor::Inference::ScopeIndexer` consults the aggregated set at
+    # its single read-before-write gate: for a `def` whose name is in
+    # `methods` on a class that equals or inherits from
+    # `receiver_constraint` (matched via `Environment#class_ordering`,
+    # the same mechanism ADR-16 Tier A uses), the method's ivar writes
+    # are folded into the class's `init_writes` set, so a sibling
+    # method reading those ivars no longer gets a `Constant[nil]`
+    # widening.
+    #
+    # The contribution can only ever *suppress* a nil widening — it
+    # never makes the analyzer stricter — so a missed or over-broad
+    # match is false-positive-safe by construction (ADR-38 § "Why this
+    # is FP-safe").
+    #
+    # ## Fields
+    #
+    # - `receiver_constraint` — fully-qualified class name (String).
+    #   The entry applies to that class and its subclasses.
+    # - `methods` — Array of Symbol method names treated as
+    #   initializers on a matching class.
+    #
+    # ## Ractor-shareability
+    #
+    # Both fields are frozen at construction (ADR-15 Phase 1);
+    # `Ractor.shareable?` returns true after `#initialize`, so the
+    # value object survives `Plugin::Registry.materialize` into a
+    # worker Ractor.
+    class AdditionalInitializer
+      attr_reader :receiver_constraint, :methods
+
+      def initialize(receiver_constraint:, methods:)
+        validate_receiver_constraint!(receiver_constraint)
+        validate_methods!(methods)
+
+        @receiver_constraint = receiver_constraint.dup.freeze
+        @methods = methods.map(&:to_sym).freeze
+        freeze
+      end
+
+      # True when `method_name` (a Symbol) is declared an initializer
+      # by this entry. The class-constraint match is the caller's
+      # responsibility (it needs the environment's class graph).
+      def covers_method?(method_name)
+        methods.include?(method_name)
+      end
+
+      def to_h
+        {
+          "receiver_constraint" => receiver_constraint,
+          "methods" => methods.map(&:to_s)
+        }
+      end
+
+      def ==(other)
+        other.is_a?(AdditionalInitializer) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      private
+
+      def validate_receiver_constraint!(value)
+        return if value.is_a?(String) && !value.empty?
+
+        raise ArgumentError,
+              "Plugin::AdditionalInitializer#receiver_constraint must be a non-empty String, " \
+              "got #{value.inspect}"
+      end
+
+      def validate_methods!(value)
+        if value.is_a?(Array) && !value.empty? &&
+           value.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
+          return
+        end
+
+        raise ArgumentError,
+              "Plugin::AdditionalInitializer#methods must be a non-empty Array of " \
+              "Symbol/non-empty String, got #{value.inspect}"
+      end
+    end
+  end
+end