rigortype 0.0.1

data/lib/rigor/type/hash_shape.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # A hash shape with statically known keys. Inhabitants are Ruby
+    # `Hash` instances whose known entries inhabit the corresponding
+    # value types. RBS records correspond to the exact closed subset;
+    # Rigor extends that carrier with optional keys, read-only entry
+    # views, and an open/closed extra-key policy.
+    #
+    # Keys are restricted to Symbol and String values. Exact closed
+    # symbol-keyed shapes erase to the RBS record syntax
+    # `{ a: Integer, ?b: String }`; all other shapes degrade to
+    # `Hash[K, V]` or raw `Hash` when no useful bounds are available.
+    #
+    # Equality and hashing are structural over the (key -> Rigor::Type)
+    # pair set and policy fields. Hash insertion order is preserved by
+    # the underlying storage but does NOT affect equality (matching
+    # Ruby's `Hash#==`).
+    #
+    # See docs/type-specification/rbs-compatible-types.md (records) and
+    # docs/type-specification/rigor-extensions.md (hash shape).
+    # rubocop:disable Metrics/ClassLength
+    class HashShape
+      ALLOWED_KEY_CLASSES = [Symbol, String].freeze
+      EXTRA_KEY_POLICIES = %i[open closed].freeze
+      POLICY_KEYWORDS = %i[required_keys optional_keys read_only_keys extra_keys].freeze
+
+      attr_reader :pairs, :required_keys, :optional_keys, :read_only_keys, :extra_keys
+
+      # @param pairs [Hash{Symbol|String => Rigor::Type}] ordered map of
+      #   keys to declared types. Keys MUST be Symbol or String;
+      #   values MUST be Rigor::Type instances. The hash is duped and
+      #   frozen at construction; callers MUST NOT mutate the input
+      #   afterwards (mutation does not affect the carrier, but the
+      #   carrier is a value object).
+      # @param required_keys [Array<Symbol|String>, nil] keys that MUST
+      #   be present. When omitted, every non-optional key is required.
+      #   When supplied without optional_keys, every remaining known key
+      #   is treated as optional.
+      # @param optional_keys [Array<Symbol|String>, nil] keys that MAY
+      #   be absent. Optional absence is not a stored nil.
+      # @param read_only_keys [Array<Symbol|String>] entries that cannot
+      #   be written through this shape view.
+      # @param extra_keys [Symbol] :closed rejects keys outside pairs;
+      #   :open permits them.
+      def initialize(pairs = nil, **keywords)
+        pairs, policy = split_constructor_args(pairs, keywords)
+        validate_pairs!(pairs)
+
+        @pairs = pairs.dup.freeze
+        apply_policy!(policy)
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        return "{}" if pairs.empty?
+
+        rendered = pairs.map { |k, v| render_entry(k, v, verbosity) }
+        rendered << "..." if open?
+        "{ #{rendered.join(', ')} }"
+      end
+
+      # Erases to the RBS record form `{ a: Integer, ?b: String }`
+      # for exact closed symbol-keyed shapes. Open shapes and
+      # string-keyed closed shapes degrade to a generic Hash bound.
+      def erase_to_rbs
+        return "{}" if pairs.empty? && closed?
+        return hash_erasure unless closed?
+        return hash_erasure if pairs.each_key.any? { |k| !k.is_a?(Symbol) }
+
+        rendered = pairs.map { |k, v| "#{record_key(k)}: #{v.erase_to_rbs}" }
+        "{ #{rendered.join(', ')} }"
+      end
+
+      def open?
+        extra_keys == :open
+      end
+
+      def closed?
+        extra_keys == :closed
+      end
+
+      def required_key?(key)
+        required_keys.include?(key)
+      end
+
+      def optional_key?(key)
+        optional_keys.include?(key)
+      end
+
+      def read_only_key?(key)
+        read_only_keys.include?(key)
+      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?(HashShape) &&
+          pairs == other.pairs &&
+          required_keys == other.required_keys &&
+          optional_keys == other.optional_keys &&
+          read_only_keys == other.read_only_keys &&
+          extra_keys == other.extra_keys
+      end
+      alias eql? ==
+
+      def hash
+        [HashShape, pairs, required_keys, optional_keys, read_only_keys, extra_keys].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::HashShape #{describe(:short)}>"
+      end
+
+      private
+
+      def split_constructor_args(pairs, keywords)
+        if pairs.nil?
+          policy = keywords.slice(*POLICY_KEYWORDS)
+          entries = keywords.except(*POLICY_KEYWORDS)
+          return [entries, policy]
+        end
+
+        unknown = keywords.keys - POLICY_KEYWORDS
+        raise ArgumentError, "unknown keywords: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
+
+        [pairs, keywords]
+      end
+
+      def validate_pairs!(pairs)
+        raise ArgumentError, "pairs must be a Hash, got #{pairs.class}" unless pairs.is_a?(Hash)
+
+        pairs.each_key do |key|
+          next if ALLOWED_KEY_CLASSES.any? { |klass| key.is_a?(klass) }
+
+          raise ArgumentError, "HashShape keys must be Symbol or String, got #{key.class}"
+        end
+      end
+
+      def apply_policy!(policy)
+        extra_keys = policy.fetch(:extra_keys, :closed)
+        unless EXTRA_KEY_POLICIES.include?(extra_keys)
+          raise ArgumentError, "extra_keys must be :open or :closed, got #{extra_keys.inspect}"
+        end
+
+        @extra_keys = extra_keys
+        @required_keys, @optional_keys = classify_keys(
+          policy.fetch(:required_keys, nil),
+          policy.fetch(:optional_keys, nil)
+        )
+        @read_only_keys = canonical_key_list(policy.fetch(:read_only_keys, []), label: "read_only_keys")
+      end
+
+      def classify_keys(required_source, optional_source)
+        required, optional = key_sources(required_source, optional_source)
+        required_keys = canonical_key_list(required, label: "required_keys")
+        optional_keys = canonical_key_list(optional, label: "optional_keys")
+        validate_key_partition(required_keys, optional_keys)
+        [required_keys, optional_keys]
+      end
+
+      def key_sources(required_source, optional_source)
+        if required_source && optional_source.nil?
+          required = Array(required_source)
+          optional = pairs.keys - required
+        else
+          optional = optional_source.nil? ? [] : Array(optional_source)
+          required = required_source.nil? ? pairs.keys - optional : Array(required_source)
+        end
+
+        [required, optional]
+      end
+
+      def canonical_key_list(keys, label:)
+        keys = Array(keys)
+        raise ArgumentError, "#{label} must not contain duplicate keys" unless keys.uniq.size == keys.size
+
+        unknown = keys - pairs.keys
+        raise ArgumentError, "#{label} contains keys not present in pairs: #{unknown.inspect}" unless unknown.empty?
+
+        keys.sort_by { |key| [key.class.name, key.inspect] }.freeze
+      end
+
+      def validate_key_partition(required, optional)
+        overlap = required & optional
+        raise ArgumentError, "required_keys and optional_keys overlap: #{overlap.inspect}" unless overlap.empty?
+
+        missing = pairs.keys - (required + optional)
+        return if missing.empty?
+
+        raise ArgumentError, "keys must be classified as required or optional: #{missing.inspect}"
+      end
+
+      def render_entry(key, value, verbosity)
+        prefix = []
+        prefix << "readonly" if read_only_key?(key)
+        rendered_key = optional_key?(key) ? "?#{render_key(key)}" : render_key(key)
+        prefix << "#{rendered_key}:"
+        "#{prefix.join(' ')} #{value.describe(verbosity)}"
+      end
+
+      def render_key(key)
+        case key
+        when Symbol then key.to_s
+        when String then key.inspect
+        end
+      end
+
+      def record_key(key)
+        optional_key?(key) ? "?#{key}" : key.to_s
+      end
+
+      def hash_erasure
+        return "Hash[top, top]" if open?
+        return "Hash" if pairs.empty?
+
+        key_type = hash_erasure_key_type
+        value_type = Type::Combinator.union(*pairs.values)
+        "Hash[#{key_type.erase_to_rbs}, #{value_type.erase_to_rbs}]"
+      end
+
+      def hash_erasure_key_type
+        key_types = pairs.keys.map { |key| Type::Combinator.nominal_of(key.class) }
+        Type::Combinator.union(*key_types)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rigor/type/nominal.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # An instance type for a Ruby class or module. The class is identified by
+    # its fully-qualified Ruby name; the registry attached to the
+    # environment owns the class lookup.
+    #
+    # Slice 4 phase 2d adds `type_args`: an ordered, frozen array of
+    # `Rigor::Type` values that carry the receiver's generic
+    # instantiation. The empty array is the canonical "raw" form
+    # (`Nominal[Array]`); a non-empty array represents an applied
+    # generic (`Nominal[Array, [Integer]]`). Two Nominals are
+    # structurally equal only when their `class_name` AND `type_args`
+    # match, so the raw form and any applied form are intentionally
+    # distinct values. Acceptance routes treat the raw form leniently
+    # for backward compatibility with phase 2b call sites that have not
+    # yet learned to carry generics.
+    #
+    # Type arguments MUST be `Rigor::Type` instances. The constructor
+    # freezes the array; callers MUST NOT mutate it after construction.
+    #
+    # See docs/type-specification/rbs-compatible-types.md.
+    class Nominal
+      attr_reader :class_name, :type_args
+
+      def initialize(class_name, type_args = [])
+        raise ArgumentError, "class_name must be a String, got #{class_name.class}" unless class_name.is_a?(String)
+        raise ArgumentError, "class_name must not be empty" if class_name.empty?
+        raise ArgumentError, "type_args must be an Array, got #{type_args.class}" unless type_args.is_a?(Array)
+
+        @class_name = class_name.freeze
+        @type_args = type_args.dup.freeze
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        return class_name if type_args.empty?
+
+        rendered = type_args.map { |t| t.describe(verbosity) }.join(", ")
+        "#{class_name}[#{rendered}]"
+      end
+
+      def erase_to_rbs
+        return class_name if type_args.empty?
+
+        rendered = type_args.map(&:erase_to_rbs).join(", ")
+        "#{class_name}[#{rendered}]"
+      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?(Nominal) && class_name == other.class_name && type_args == other.type_args
+      end
+      alias eql? ==
+
+      def hash
+        [Nominal, class_name, type_args].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Nominal #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/singleton.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # The singleton type for a Ruby class or module. Inhabitants are the
+    # class object itself (e.g. the constant `Foo`), not its instances.
+    # In RBS this corresponds to `singleton(Foo)`.
+    #
+    # `Singleton[Foo]` and `Nominal[Foo]` share the same `class_name` but
+    # are NEVER equal; they describe disjoint values (the class object vs.
+    # instances of the class).
+    #
+    # See docs/type-specification/rbs-compatible-types.md (singleton(T)).
+    class Singleton
+      attr_reader :class_name
+
+      def initialize(class_name)
+        raise ArgumentError, "class_name must be a String, got #{class_name.class}" unless class_name.is_a?(String)
+        raise ArgumentError, "class_name must not be empty" if class_name.empty?
+
+        @class_name = class_name.freeze
+        freeze
+      end
+
+      def describe(_verbosity = :short)
+        "singleton(#{class_name})"
+      end
+
+      def erase_to_rbs
+        "singleton(#{class_name})"
+      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?(Singleton) && class_name == other.class_name
+      end
+      alias eql? ==
+
+      def hash
+        [Singleton, class_name].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Singleton #{class_name}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/top.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # The top of the value lattice: contains every value, including untyped
+    # boundaries. See docs/type-specification/special-types.md.
+    class Top
+      class << self
+        def instance
+          @instance ||= new.freeze
+        end
+
+        private :new
+      end
+
+      def describe(_verbosity = :short)
+        "top"
+      end
+
+      def erase_to_rbs
+        "top"
+      end
+
+      def top
+        Trinary.yes
+      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?(Top)
+      end
+      alias eql? ==
+
+      def hash
+        Top.hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Top>"
+      end
+    end
+  end
+end

data/lib/rigor/type/tuple.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # A heterogeneous, fixed-arity array shape. Inhabitants are exactly
+    # the Ruby `Array` instances whose length matches `elements.size`
+    # and whose element at position `i` inhabits `elements[i]`.
+    #
+    # In RBS this corresponds to the tuple form `[A, B, C]`. A tuple
+    # is always a subtype of `Array[union(elements)]`; method dispatch
+    # therefore degrades to the underlying `Nominal[Array, [union]]`
+    # while acceptance keeps the per-position precision.
+    #
+    # Slice 5 phase 1 introduces the carrier and surfaces it from the
+    # `ArrayNode` literal handler when every element is a non-splat
+    # value. Tuple-aware refinements for `tuple[0]`, `tuple.first`, and
+    # destructuring assignment are deferred to Slice 5 phase 2; they
+    # will run as a higher-priority dispatch tier above
+    # {Rigor::Inference::MethodDispatcher::RbsDispatch}.
+    #
+    # Equality and hashing are structural across an ordered, frozen
+    # element list. The empty Tuple `Tuple[]` is permitted; the array
+    # literal handler keeps `[]` as raw `Nominal[Array]` (no element
+    # evidence to lock the arity), but external constructors MAY build
+    # `Tuple[]` directly when the zero-arity discipline is intended.
+    #
+    # See docs/type-specification/rbs-compatible-types.md (tuple) and
+    # docs/type-specification/rigor-extensions.md (hash-shape and
+    # tuple kin).
+    class Tuple
+      attr_reader :elements
+
+      def initialize(elements)
+        raise ArgumentError, "elements must be an Array, got #{elements.class}" unless elements.is_a?(Array)
+
+        @elements = elements.dup.freeze
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        return "[]" if elements.empty?
+
+        "[#{elements.map { |t| t.describe(verbosity) }.join(', ')}]"
+      end
+
+      def erase_to_rbs
+        return "[]" if elements.empty?
+
+        "[#{elements.map(&:erase_to_rbs).join(', ')}]"
+      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?(Tuple) && elements == other.elements
+      end
+      alias eql? ==
+
+      def hash
+        [Tuple, elements].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Tuple #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/union.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # A normalized non-empty union of two or more distinct types. Unions are
+    # constructed exclusively through Rigor::Type::Combinator.union, which
+    # flattens nested unions, deduplicates structurally-equal members, and
+    # collapses single-member or empty results to the appropriate scalar
+    # type. Direct calls to .new are an internal contract: callers MUST pass
+    # an already-normalized members array.
+    #
+    # See docs/type-specification/normalization.md.
+    class Union
+      attr_reader :members
+
+      def initialize(members)
+        unless members.is_a?(Array) && members.size >= 2
+          raise ArgumentError, "Union requires at least two members; use Combinator.union for normalization"
+        end
+
+        @members = members.freeze
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        members.map { |m| m.describe(verbosity) }.join(" | ")
+      end
+
+      def erase_to_rbs
+        members.map(&:erase_to_rbs).join(" | ")
+      end
+
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.no
+      end
+
+      def dynamic
+        members.any? { |m| m.respond_to?(:dynamic) && m.dynamic.yes? } ? Trinary.maybe : Trinary.no
+      end
+
+      def accepts(other, mode: :gradual)
+        Inference::Acceptance.accepts(self, other, mode: mode)
+      end
+
+      def ==(other)
+        other.is_a?(Union) && members == other.members
+      end
+      alias eql? ==
+
+      def hash
+        [Union, members].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Union #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Documentation-only ducktype module that names the contract every Rigor
+  # type instance MUST satisfy. Concrete type classes do NOT include
+  # Rigor::Type; the ducktype is observed structurally.
+  #
+  # See docs/internal-spec/internal-type-api.md for the binding contract.
+  module Type
+  end
+end
+
+require_relative "type/top"
+require_relative "type/bot"
+require_relative "type/dynamic"
+require_relative "type/nominal"
+require_relative "type/singleton"
+require_relative "type/constant"
+require_relative "type/tuple"
+require_relative "type/hash_shape"
+require_relative "type/union"
+require_relative "type/accepts_result"
+require_relative "type/combinator"

data/lib/rigor/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rigor
+  VERSION = "0.0.1"
+end

data/lib/rigor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "rigor/version"
+require_relative "rigor/configuration"
+require_relative "rigor/trinary"
+require_relative "rigor/type"
+require_relative "rigor/ast"
+require_relative "rigor/environment"
+require_relative "rigor/rbs_extended"
+require_relative "rigor/testing"
+require_relative "rigor/inference/fallback"
+require_relative "rigor/inference/fallback_tracer"
+require_relative "rigor/inference/acceptance"
+require_relative "rigor/inference/rbs_type_translator"
+require_relative "rigor/inference/method_dispatcher"
+require_relative "rigor/inference/expression_typer"
+require_relative "rigor/inference/method_parameter_binder"
+require_relative "rigor/inference/closure_escape_analyzer"
+require_relative "rigor/inference/statement_evaluator"
+require_relative "rigor/scope"
+require_relative "rigor/source"
+require_relative "rigor/inference/scope_indexer"
+require_relative "rigor/inference/coverage_scanner"
+require_relative "rigor/analysis/fact_store"
+require_relative "rigor/analysis/diagnostic"
+require_relative "rigor/analysis/result"
+require_relative "rigor/analysis/check_rules"
+require_relative "rigor/analysis/runner"
+require_relative "rigor/cli"