rigortype 0.0.1

data/lib/rigor/trinary.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Three-valued logic value object shared by capability queries, relational
+  # queries, and any analyzer surface that distinguishes "proven yes",
+  # "proven no", and "cannot prove either".
+  #
+  # See docs/type-specification/relations-and-certainty.md for semantics and
+  # docs/internal-spec/internal-type-api.md for the contract.
+  class Trinary
+    VALUES = %i[yes no maybe].freeze
+
+    class << self
+      def yes
+        @yes ||= new(:yes).freeze
+      end
+
+      def no
+        @no ||= new(:no).freeze
+      end
+
+      def maybe
+        @maybe ||= new(:maybe).freeze
+      end
+
+      def from_symbol(symbol)
+        case symbol
+        when :yes then yes
+        when :no then no
+        when :maybe then maybe
+        else
+          raise ArgumentError, "unknown trinary value: #{symbol.inspect}"
+        end
+      end
+    end
+
+    attr_reader :value
+
+    def initialize(value)
+      raise ArgumentError, "unknown trinary value: #{value.inspect}" unless VALUES.include?(value)
+
+      @value = value
+    end
+
+    def yes?
+      value == :yes
+    end
+
+    def no?
+      value == :no
+    end
+
+    def maybe?
+      value == :maybe
+    end
+
+    def negate
+      case value
+      when :yes then self.class.no
+      when :no then self.class.yes
+      when :maybe then self.class.maybe
+      end
+    end
+
+    # Conjunction. yes & yes = yes, no with anything = no, otherwise maybe.
+    def and(other)
+      coerced = coerce(other)
+      return self.class.no if no? || coerced.no?
+      return self.class.yes if yes? && coerced.yes?
+
+      self.class.maybe
+    end
+
+    # Disjunction. yes with anything = yes, no & no = no, otherwise maybe.
+    def or(other)
+      coerced = coerce(other)
+      return self.class.yes if yes? || coerced.yes?
+      return self.class.no if no? && coerced.no?
+
+      self.class.maybe
+    end
+
+    def ==(other)
+      other.is_a?(Trinary) && value == other.value
+    end
+    alias eql? ==
+
+    def hash
+      value.hash
+    end
+
+    def to_s
+      value.to_s
+    end
+
+    def inspect
+      "#<Rigor::Trinary #{value}>"
+    end
+
+    private
+
+    def coerce(other)
+      return other if other.is_a?(Trinary)
+
+      raise TypeError, "expected Rigor::Trinary, got #{other.class}"
+    end
+  end
+end

data/lib/rigor/type/accepts_result.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # Immutable value object returned by `Rigor::Type#accepts(other, mode:)`.
+    # Carries the three-valued answer alongside the boundary mode the answer
+    # was computed under and an ordered list of textual reasons describing
+    # which rules fired.
+    #
+    # AcceptsResult is the dual of `SubtypeResult` (Slice 5+). Acceptance
+    # answers "is `other` passable to `self` at a method-parameter or
+    # assignment boundary?", consulting the gradual-typing rules in
+    # docs/type-specification/value-lattice.md when `mode` is `:gradual`,
+    # and the strict subset relation when `mode` is `:strict`. Phase 2c
+    # ships full `:gradual` semantics; `:strict` is reserved for later
+    # slices and currently raises ArgumentError.
+    #
+    # Reasons are stored as plain strings for now. Slice 5+ MAY upgrade
+    # them to structured records (rule id, supporting facts, dynamic
+    # provenance); callers MUST treat the reasons array as opaque except
+    # for human-readable logging.
+    #
+    # See docs/internal-spec/internal-type-api.md ("Result Value Objects").
+    class AcceptsResult
+      MODES = %i[gradual strict].freeze
+      private_constant :MODES
+
+      attr_reader :trinary, :mode, :reasons
+
+      # @param trinary [Rigor::Trinary]
+      # @param mode [Symbol] currently `:gradual` (default) or `:strict`.
+      # @param reasons [Array<String>, String, nil] textual reasons; a
+      #   single string is wrapped, `nil` becomes an empty array.
+      def initialize(trinary, mode: :gradual, reasons: nil)
+        raise ArgumentError, "trinary must be Rigor::Trinary, got #{trinary.class}" unless trinary.is_a?(Trinary)
+        raise ArgumentError, "mode must be one of #{MODES.inspect}, got #{mode.inspect}" unless MODES.include?(mode)
+
+        @trinary = trinary
+        @mode = mode
+        @reasons = normalize_reasons(reasons).freeze
+        freeze
+      end
+
+      class << self
+        def yes(mode: :gradual, reasons: nil)
+          new(Trinary.yes, mode: mode, reasons: reasons)
+        end
+
+        def no(mode: :gradual, reasons: nil)
+          new(Trinary.no, mode: mode, reasons: reasons)
+        end
+
+        def maybe(mode: :gradual, reasons: nil)
+          new(Trinary.maybe, mode: mode, reasons: reasons)
+        end
+      end
+
+      def yes?
+        trinary.yes?
+      end
+
+      def no?
+        trinary.no?
+      end
+
+      def maybe?
+        trinary.maybe?
+      end
+
+      # Returns a new AcceptsResult whose reasons list is `self.reasons`
+      # with `reason` appended. Used by combinator-style routing in
+      # {Rigor::Inference::Acceptance} to thread context through nested
+      # acceptance checks without mutating any object.
+      def with_reason(reason)
+        return self if reason.nil? || reason.empty?
+
+        self.class.new(trinary, mode: mode, reasons: reasons + [reason])
+      end
+
+      def ==(other)
+        other.is_a?(AcceptsResult) &&
+          trinary == other.trinary &&
+          mode == other.mode &&
+          reasons == other.reasons
+      end
+      alias eql? ==
+
+      def hash
+        [AcceptsResult, trinary, mode, reasons].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::AcceptsResult #{trinary.inspect} mode=#{mode}>"
+      end
+
+      private
+
+      def normalize_reasons(reasons)
+        case reasons
+        when nil then []
+        when Array then reasons.dup
+        else [reasons.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/rigor/type/bot.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # The bottom of the value lattice: contains no values. The result type of
+    # expressions that cannot terminate normally. See
+    # docs/type-specification/special-types.md.
+    class Bot
+      class << self
+        def instance
+          @instance ||= new.freeze
+        end
+
+        private :new
+      end
+
+      def describe(_verbosity = :short)
+        "bot"
+      end
+
+      def erase_to_rbs
+        "bot"
+      end
+
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.yes
+      end
+
+      def dynamic
+        Trinary.no
+      end
+
+      def accepts(other, mode: :gradual)
+        Inference::Acceptance.accepts(self, other, mode: mode)
+      end
+
+      def ==(other)
+        other.is_a?(Bot)
+      end
+      alias eql? ==
+
+      def hash
+        Bot.hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Bot>"
+      end
+    end
+  end
+end

data/lib/rigor/type/combinator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "top"
+require_relative "bot"
+require_relative "dynamic"
+require_relative "nominal"
+require_relative "singleton"
+require_relative "constant"
+require_relative "tuple"
+require_relative "hash_shape"
+require_relative "union"
+
+module Rigor
+  module Type
+    # Factory entry point that routes every public construction through the
+    # deterministic normalization rules. Production code paths MUST go
+    # through Rigor::Type::Combinator. Direct constructor calls are an
+    # internal escape hatch for tests and for combinator's own
+    # implementation.
+    #
+    # See docs/internal-spec/internal-type-api.md and
+    # docs/type-specification/normalization.md.
+    module Combinator
+      module_function
+
+      def top
+        Top.instance
+      end
+
+      def bot
+        Bot.instance
+      end
+
+      def untyped
+        @untyped ||= Dynamic.new(top)
+      end
+
+      # Wraps the static facet in a Dynamic[T] carrier. Idempotent on the
+      # static facet so Dynamic[Dynamic[T]] collapses to Dynamic[T] per the
+      # value-lattice algebra.
+      def dynamic(static_facet)
+        return untyped if static_facet.equal?(top)
+
+        facet = static_facet.is_a?(Dynamic) ? static_facet.static_facet : static_facet
+        return untyped if facet.is_a?(Top)
+
+        Dynamic.new(facet)
+      end
+
+      # Constructs a Nominal type. Slice 4 phase 2d accepts an optional
+      # `type_args:` array, an ordered list of Rigor::Type values that
+      # carry the receiver's generic instantiation (`Array[Integer]` is
+      # `Nominal["Array", [Nominal["Integer"]]]`). Omitting the keyword
+      # produces the raw form `Nominal["Array"]`, which is structurally
+      # distinct from any applied form.
+      def nominal_of(class_name_or_object, type_args: [])
+        Nominal.new(resolve_class_name(class_name_or_object), type_args)
+      end
+
+      def singleton_of(class_name_or_object)
+        Singleton.new(resolve_class_name(class_name_or_object))
+      end
+
+      def constant_of(value)
+        Constant.new(value)
+      end
+
+      # Constructs a heterogeneous, fixed-arity Tuple from positional
+      # element types. `tuple_of()` produces the empty tuple `Tuple[]`,
+      # which is structurally distinct from the raw `Nominal[Array]`.
+      def tuple_of(*elements)
+        Tuple.new(elements)
+      end
+
+      # Constructs a HashShape from an ordered (Symbol|String) -> type
+      # map. The argument is duped and frozen by the carrier; callers
+      # MUST NOT rely on later mutation.
+      def hash_shape_of(pairs = nil, **options)
+        if pairs.nil?
+          pairs = options
+          options = {}
+        end
+
+        HashShape.new(pairs, **options)
+      end
+
+      # Normalized union. Flattens nested Unions, deduplicates structurally
+      # equal members, drops Bot, and collapses 0/1-member results.
+      def union(*types)
+        collapse_union(normalized_union_members(types))
+      end
+
+      class << self
+        private
+
+        def normalized_union_members(types)
+          flattened = []
+          types.each { |t| flatten_into(flattened, t) }
+          flattened.reject! { |t| t.is_a?(Bot) }
+
+          return [top] if flattened.any?(Top)
+
+          unique_members(flattened)
+        end
+
+        def unique_members(types)
+          types.each_with_object([]) do |type, unique|
+            unique << type unless unique.any? { |member| member == type }
+          end
+        end
+
+        def collapse_union(types)
+          case types.size
+          when 0 then bot
+          when 1 then types.first
+          else Union.new(sort_members(types))
+          end
+        end
+
+        def resolve_class_name(class_name_or_object)
+          name =
+            case class_name_or_object
+            when Module then class_name_or_object.name
+            when String then class_name_or_object
+            else
+              raise ArgumentError, "expected Class/Module or String, got #{class_name_or_object.class}"
+            end
+
+          raise ArgumentError, "anonymous class has no name" if name.nil? || name.empty?
+
+          name
+        end
+
+        def flatten_into(acc, type)
+          if type.is_a?(Union)
+            type.members.each { |m| flatten_into(acc, m) }
+          else
+            acc << type
+          end
+        end
+
+        def sort_members(members)
+          members.sort_by { |m| m.describe(:short) }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/type/constant.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # A literal carrier under ADR-3 OQ1 Option C (Hybrid). Wraps a Ruby
+    # literal value of one of the supported immutable-ish classes. Compound
+    # literal shapes (Tuple, HashShape, Record) get dedicated classes in
+    # later slices; Range is carried only when both static endpoints are
+    # known enough for tuple slicing.
+    #
+    # See docs/adr/4-type-inference-engine.md for the tentative answer to
+    # the open question and docs/type-specification/rigor-extensions.md for
+    # the refinement neighbourhood this carrier lives in.
+    class Constant
+      SCALAR_CLASSES = [
+        Integer,
+        Float,
+        String,
+        Symbol,
+        Range,
+        Rational,
+        Complex,
+        TrueClass,
+        FalseClass,
+        NilClass
+      ].freeze
+
+      RBS_LITERAL_CLASSES = {
+        TrueClass => "true",
+        FalseClass => "false",
+        NilClass => "nil"
+      }.freeze
+
+      attr_reader :value
+
+      def initialize(value)
+        unless SCALAR_CLASSES.any? { |klass| value.is_a?(klass) }
+          raise ArgumentError, "Rigor::Type::Constant only carries scalar literals; got #{value.class}"
+        end
+
+        @value = value.is_a?(String) ? value.dup.freeze : value
+        freeze
+      end
+
+      def describe(_verbosity = :short)
+        value.inspect
+      end
+
+      def erase_to_rbs
+        case value
+        when true then "true"
+        when false then "false"
+        when nil then "nil"
+        else value.class.name
+        end
+      end
+
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.no
+      end
+
+      def dynamic
+        Trinary.no
+      end
+
+      def accepts(other, mode: :gradual)
+        Inference::Acceptance.accepts(self, other, mode: mode)
+      end
+
+      def ==(other)
+        other.is_a?(Constant) && value.class == other.value.class && value == other.value
+      end
+      alias eql? ==
+
+      def hash
+        [Constant, value.class, value].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Constant #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/dynamic.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # The dynamic-origin wrapper: marks values whose type came from an
+    # unchecked source. Carries a static facet that records the analyzer's
+    # best static knowledge. See docs/type-specification/value-lattice.md
+    # for the algebra and docs/type-specification/special-types.md for the
+    # untyped/Dynamic[T] relationship.
+    #
+    # Construct via Rigor::Type::Combinator.dynamic(static_facet).
+    class Dynamic
+      attr_reader :static_facet
+
+      def initialize(static_facet)
+        @static_facet = static_facet
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        "Dynamic[#{static_facet.describe(verbosity)}]"
+      end
+
+      def erase_to_rbs
+        "untyped"
+      end
+
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.no
+      end
+
+      def dynamic
+        Trinary.yes
+      end
+
+      def accepts(other, mode: :gradual)
+        Inference::Acceptance.accepts(self, other, mode: mode)
+      end
+
+      def ==(other)
+        other.is_a?(Dynamic) && static_facet == other.static_facet
+      end
+      alias eql? ==
+
+      def hash
+        [Dynamic, static_facet].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Dynamic #{describe(:short)}>"
+      end
+    end
+  end
+end