rigortype 0.0.2 → 0.0.3

data/lib/rigor/rbs_extended.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "type"
+require_relative "builtins/imported_refinements"
 
 module Rigor
   # Slice 7 phase 15 — first-preview reader for the
@@ -40,7 +41,7 @@ module Rigor
   # `::Foo::Bar` style constant path. Negative refinements
   # (`~T`), intersections, and unions are deferred to the
   # next iteration.
-  module RbsExtended
+  module RbsExtended # rubocop:disable Metrics/ModuleLength
     DIRECTIVE_PREFIX = "rigor:v1:"
 
     # Returned for `predicate-if-true` / `predicate-if-false`.
@@ -190,5 +191,68 @@ module Rigor
         negative: match[:negation].to_s == "~"
       )
     end
+
+    # Reads the `rigor:v1:return: <kebab-name>` directive off
+    # `RBS::Definition::Method#annotations`. The directive
+    # overrides a method's RBS-declared return type with one of
+    # the imported-built-in refinements registered in
+    # `Rigor::Builtins::ImportedRefinements`. The override is the
+    # primary integration path for refinement carriers
+    # (`non-empty-string`, `positive-int`, `non-empty-array`, …)
+    # in v0.0 — annotation-driven, opt-in per method, and never
+    # silently rewrites a hand-authored RBS signature outside the
+    # annotation.
+    #
+    # Example annotation in an RBS file:
+    #
+    #   class User
+    #     %a{rigor:v1:return: non-empty-string}
+    #     def name: () -> String
+    #   end
+    #
+    # The RBS-declared return is `String`. The override
+    # tightens it to `non-empty-string` (i.e.
+    # `Difference[String, ""]`) for callers; RBS erasure of the
+    # tightened return goes back to `String` so the round-trip
+    # to ordinary RBS is unaffected.
+    #
+    # Returns the resolved `Rigor::Type` value, or `nil` when:
+    # - the method has no annotations,
+    # - none of the annotations match the `rigor:v1:return:`
+    #   directive,
+    # - the directive's payload names a refinement not
+    #   registered in `Rigor::Builtins::ImportedRefinements`
+    #   (the analyzer prefers a silent miss over crashing on a
+    #   typo; future slices MAY surface the miss as a
+    #   `:warning` self-diagnostic).
+    def read_return_type_override(method_def)
+      return nil if method_def.nil?
+
+      annotations = method_def.annotations
+      return nil if annotations.nil? || annotations.empty?
+
+      annotations.each do |annotation|
+        type = parse_return_type_override(annotation.string)
+        return type if type
+      end
+      nil
+    end
+
+    RETURN_DIRECTIVE_PATTERN = /
+      \A
+      rigor:v1:return:
+      \s+
+      (?<refinement>[a-z][a-z0-9-]*)
+      \s*
+      \z
+    /x
+    private_constant :RETURN_DIRECTIVE_PATTERN
+
+    def parse_return_type_override(string)
+      match = RETURN_DIRECTIVE_PATTERN.match(string)
+      return nil if match.nil?
+
+      Builtins::ImportedRefinements.lookup(match[:refinement])
+    end
   end
 end

data/lib/rigor/scope.rb

@@ -250,6 +250,20 @@ module Rigor
       table[method_name.to_sym]
     end
 
+    # v0.0.3 A — top-level def lookup for implicit-self
+    # calls. Returns the `Prism::DefNode` for a top-level
+    # (or DSL-block-nested, outside any class body) `def
+    # <method_name>` in the file, or nil. The sentinel key
+    # is owned by `Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY`;
+    # consumers should treat its presence as an opaque
+    # implementation detail and go through this accessor.
+    def top_level_def_for(method_name)
+      table = @discovered_def_nodes[Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY]
+      return nil unless table
+
+      table[method_name.to_sym]
+    end
+
     def with_discovered_def_nodes(table)
       rebuild(discovered_def_nodes: table)
     end

data/lib/rigor/type/combinator.rb

@@ -6,9 +6,11 @@ require_relative "dynamic"
 require_relative "nominal"
 require_relative "singleton"
 require_relative "constant"
+require_relative "integer_range"
 require_relative "tuple"
 require_relative "hash_shape"
 require_relative "union"
+require_relative "difference"
 
 module Rigor
   module Type
@@ -20,7 +22,7 @@ module Rigor
     #
     # See docs/internal-spec/internal-type-api.md and
     # docs/type-specification/normalization.md.
-    module Combinator
+    module Combinator # rubocop:disable Metrics/ModuleLength
       module_function
 
       def top
@@ -65,6 +67,72 @@ module Rigor
         Constant.new(value)
       end
 
+      # Bounded-integer carrier. Each bound is either an `Integer` or
+      # one of `:neg_infinity` / `:pos_infinity` (sentinels exposed as
+      # `IntegerRange::NEG_INFINITY` / `POS_INFINITY`).
+      def integer_range(min, max)
+        IntegerRange.new(min, max)
+      end
+
+      # Convenience aliases for the most common bounded shapes. The
+      # named alias survives roundtrip through `describe` for nicer
+      # human-facing output.
+      def positive_int
+        IntegerRange.new(1, IntegerRange::POS_INFINITY)
+      end
+
+      def non_negative_int
+        IntegerRange.new(0, IntegerRange::POS_INFINITY)
+      end
+
+      def negative_int
+        IntegerRange.new(IntegerRange::NEG_INFINITY, -1)
+      end
+
+      def non_positive_int
+        IntegerRange.new(IntegerRange::NEG_INFINITY, 0)
+      end
+
+      def universal_int
+        IntegerRange.new(IntegerRange::NEG_INFINITY, IntegerRange::POS_INFINITY)
+      end
+
+      # Point-removal refinement carrier (ADR-3 OQ3 Option C). Use
+      # `non_empty_string` / `non_zero_int` / `non_empty_array` /
+      # `non_empty_hash` for the imported built-in shapes; raw
+      # `difference(base, removed)` for ad-hoc refinements an
+      # `RBS::Extended` annotation introduces.
+      def difference(base, removed)
+        Difference.new(base, removed)
+      end
+
+      def non_empty_string
+        Difference.new(nominal_of("String"), constant_of(""))
+      end
+
+      def non_zero_int
+        Difference.new(nominal_of("Integer"), constant_of(0))
+      end
+
+      # `non-empty-array[T]` requires the element type so the
+      # `Nominal[Array, [T]]` projection through Array#first /
+      # #last keeps element precision intact. The default
+      # `Top` admits any array element when the caller does
+      # not have a more specific element type.
+      def non_empty_array(element = top)
+        Difference.new(
+          nominal_of("Array", type_args: [element]),
+          tuple_of
+        )
+      end
+
+      def non_empty_hash(key = top, value = top)
+        Difference.new(
+          nominal_of("Hash", type_args: [key, value]),
+          hash_shape_of({})
+        )
+      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]`.

data/lib/rigor/type/difference.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # `Difference[base, removed]` — the value set of `base` minus
+    # the value set of `removed`. Implements the point-removal
+    # half of the OQ3 refinement-carrier strategy
+    # ([ADR-3](docs/adr/3-type-representation.md), Working
+    # Decision Option C):
+    #
+    #   non-empty-string   = Difference[Nominal[String], Constant[""]]
+    #   non-zero-int       = Difference[Nominal[Integer], Constant[0]]
+    #   non-empty-array[T] = Difference[Nominal[Array, [T]], Tuple[]]
+    #   non-empty-hash[K,V] = Difference[Nominal[Hash, [K,V]], HashShape{}]
+    #
+    # The carrier itself is structural: it stores `base` and
+    # `removed` as inner `Type` references and answers projection
+    # / acceptance / display questions by composing those inner
+    # answers per the lattice algebra in
+    # [`value-lattice.md`](docs/type-specification/value-lattice.md).
+    # The canonical-name registry (display side) lives in
+    # `Rigor::Type::Combinator` and prints kebab-case names like
+    # `non-empty-string` for the recognised shapes; unrecognised
+    # differences fall back to the raw `base - removed`
+    # operator form per [`type-operators.md`](docs/type-specification/type-operators.md).
+    #
+    # Construction goes through `Type::Combinator.difference` /
+    # `Combinator.non_empty_string` etc. — direct `.new` calls
+    # are an internal contract; callers MUST ensure both bounds
+    # are valid `Rigor::Type` values and that `removed` is a
+    # subtype-or-equal of `base` (otherwise the difference does
+    # not narrow anything and a normalisation upstream should
+    # collapse to `base`).
+    class Difference
+      attr_reader :base, :removed
+
+      def initialize(base, removed)
+        @base = base
+        @removed = removed
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        named = canonical_name
+        return named if named
+
+        "#{base.describe(verbosity)} - #{removed.describe(verbosity)}"
+      end
+
+      # Erases to the base nominal: every refinement MUST erase
+      # to its base per [`rbs-erasure.md`](docs/type-specification/rbs-erasure.md).
+      def erase_to_rbs
+        base.erase_to_rbs
+      end
+
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.no
+      end
+
+      def dynamic
+        base.respond_to?(:dynamic) ? base.dynamic : Trinary.no
+      end
+
+      def accepts(other, mode: :gradual)
+        Inference::Acceptance.accepts(self, other, mode: mode)
+      end
+
+      def ==(other)
+        other.is_a?(Difference) && base == other.base && removed == other.removed
+      end
+      alias eql? ==
+
+      def hash
+        [Difference, base, removed].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Difference #{describe(:short)}>"
+      end
+
+      private
+
+      # Renders the kebab-case shorthand for recognised
+      # imported-built-in shapes. Parameterised bases keep their
+      # type-args in the canonical form (`non-empty-array[T]`,
+      # `non-empty-hash[K, V]`) so element-precision survives the
+      # display round-trip. Unrecognised shapes fall back to the
+      # raw `base - removed` operator form.
+      #
+      # The recognised set is kept in sync with the imported-built-in
+      # catalogue ([`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md)).
+      def canonical_name
+        return nil unless base.is_a?(Nominal)
+
+        send(CANONICAL_HANDLERS[base.class_name] || :no_canonical_name)
+      end
+
+      CANONICAL_HANDLERS = {
+        "String" => :string_canonical_name,
+        "Integer" => :integer_canonical_name,
+        "Array" => :array_canonical_name_if_empty,
+        "Hash" => :hash_canonical_name_if_empty
+      }.freeze
+      private_constant :CANONICAL_HANDLERS
+
+      def no_canonical_name
+        nil
+      end
+
+      def string_canonical_name
+        return nil unless removed.is_a?(Constant) && removed.value == ""
+
+        "non-empty-string"
+      end
+
+      def integer_canonical_name
+        return nil unless removed.is_a?(Constant) && removed.value.is_a?(Integer) && removed.value.zero?
+
+        "non-zero-int"
+      end
+
+      def array_canonical_name_if_empty
+        return nil unless removed.is_a?(Tuple) && removed.elements.empty?
+
+        array_canonical_name
+      end
+
+      def hash_canonical_name_if_empty
+        return nil unless removed.is_a?(HashShape) && removed.pairs.empty?
+
+        hash_canonical_name
+      end
+
+      def array_canonical_name
+        elem = base.type_args.first
+        return "non-empty-array" if elem.nil?
+
+        "non-empty-array[#{elem.describe}]"
+      end
+
+      def hash_canonical_name
+        key, value = base.type_args
+        return "non-empty-hash" if key.nil? || value.nil?
+
+        "non-empty-hash[#{key.describe}, #{value.describe}]"
+      end
+    end
+  end
+end

data/lib/rigor/type/integer_range.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # A bounded integer range carrier. Each bound is either an `Integer`
+    # or one of the symbolic infinities `:neg_infinity` / `:pos_infinity`.
+    # Inspired by PHPStan's `int<min, max>` family — the named aliases
+    # `positive-int` (1..), `non-negative-int` (0..), `negative-int`
+    # (..-1), `non-positive-int` (..0) all surface through this single
+    # carrier and are recovered in `describe` for human-friendly output.
+    #
+    # Constraints on construction:
+    # - both bounds must be either `Integer` or one of the two infinity
+    #   sentinels;
+    # - if both bounds are concrete, `min <= max` must hold;
+    # - the universal case `(-∞, +∞)` is structurally distinct from
+    #   `Nominal[Integer]` — it carries no extra information today but
+    #   keeps the carrier closed under range narrowing.
+    #
+    # Erasure to RBS is always "Integer": RBS itself does not natively
+    # express bounded integer ranges.
+    class IntegerRange
+      NEG_INFINITY = :neg_infinity
+      POS_INFINITY = :pos_infinity
+      INFINITIES = [NEG_INFINITY, POS_INFINITY].freeze
+
+      attr_reader :min, :max
+
+      def initialize(min, max)
+        validate_bound!(min, "min")
+        validate_bound!(max, "max")
+        if min.is_a?(Integer) && max.is_a?(Integer) && min > max
+          raise ArgumentError, "IntegerRange requires min (#{min}) <= max (#{max})"
+        end
+        if min == POS_INFINITY || max == NEG_INFINITY
+          raise ArgumentError, "IntegerRange bounds out of order: min=#{min.inspect}, max=#{max.inspect}"
+        end
+
+        @min = min
+        @max = max
+        freeze
+      end
+
+      def universal?
+        min == NEG_INFINITY && max == POS_INFINITY
+      end
+
+      def finite?
+        min.is_a?(Integer) && max.is_a?(Integer)
+      end
+
+      def cardinality
+        finite? ? (max - min + 1) : Float::INFINITY
+      end
+
+      def covers?(int)
+        return false unless int.is_a?(Integer)
+
+        int.between?(lower, upper)
+      end
+
+      # Returns the lower bound as a numeric (with `-Float::INFINITY` for
+      # `:neg_infinity`). Use this in arithmetic comparisons; never compare
+      # `:neg_infinity` directly with an `Integer`.
+      def lower
+        min == NEG_INFINITY ? -Float::INFINITY : min
+      end
+
+      def upper
+        max == POS_INFINITY ? Float::INFINITY : max
+      end
+
+      ALIAS_NAMES = {
+        [NEG_INFINITY, POS_INFINITY] => "int",
+        [1, POS_INFINITY] => "positive-int",
+        [0, POS_INFINITY] => "non-negative-int",
+        [NEG_INFINITY, -1] => "negative-int",
+        [NEG_INFINITY, 0] => "non-positive-int"
+      }.freeze
+
+      def describe(_verbosity = :short)
+        ALIAS_NAMES[[min, max]] || generic_description
+      end
+
+      def generic_description
+        return "int<#{min}, max>" if max == POS_INFINITY
+        return "int<min, #{max}>" if min == NEG_INFINITY
+
+        "int<#{min}, #{max}>"
+      end
+
+      def erase_to_rbs
+        "Integer"
+      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?(IntegerRange) && min == other.min && max == other.max
+      end
+      alias eql? ==
+
+      def hash
+        [IntegerRange, min, max].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::IntegerRange #{describe(:short)}>"
+      end
+
+      private
+
+      def validate_bound!(bound, label)
+        return if bound.is_a?(Integer) || INFINITIES.include?(bound)
+
+        raise ArgumentError,
+              "IntegerRange #{label} must be Integer or :neg_infinity/:pos_infinity, got #{bound.inspect}"
+      end
+    end
+  end
+end

data/lib/rigor/type.rb

@@ -16,8 +16,10 @@ require_relative "type/dynamic"
 require_relative "type/nominal"
 require_relative "type/singleton"
 require_relative "type/constant"
+require_relative "type/integer_range"
 require_relative "type/tuple"
 require_relative "type/hash_shape"
 require_relative "type/union"
+require_relative "type/difference"
 require_relative "type/accepts_result"
 require_relative "type/combinator"

data/lib/rigor/version.rb

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

data/sig/rigor/rbs_extended.rbs

@@ -39,5 +39,8 @@ module Rigor
 
     def self?.read_assert_effects: (untyped method_def) -> Array[AssertEffect]
     def self?.parse_assert_annotation: (String string) -> AssertEffect?
+
+    def self?.read_return_type_override: (untyped method_def) -> Type::t?
+    def self?.parse_return_type_override: (String string) -> Type::t?
   end
 end

data/sig/rigor/scope.rbs

@@ -38,6 +38,7 @@ module Rigor
     def discovered_method?: (String | Symbol class_name, String | Symbol method_name, Symbol kind) -> bool
     def with_discovered_def_nodes: (Hash[String, Hash[Symbol, untyped]] table) -> Scope
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
+    def top_level_def_for: (String | Symbol method_name) -> untyped?
     def with_fact: (Analysis::FactStore::Fact fact) -> Scope
     def with_self_type: (Type::t? type) -> Scope
     def with_declared_types: (Hash[untyped, Type::t] table) -> Scope

data/sig/rigor/type.rbs

@@ -1,6 +1,6 @@
 module Rigor
   module Type
-    type t = Top | Bot | Dynamic | Constant | Nominal | Singleton | Union | Tuple | HashShape
+    type t = Top | Bot | Dynamic | Constant | IntegerRange | Nominal | Singleton | Union | Difference | Tuple | HashShape
 
     type accepts_mode = :strict | :gradual | :loose
 
@@ -58,6 +58,30 @@ module Rigor
       def inspect: () -> String
     end
 
+    class IntegerRange
+      NEG_INFINITY: Symbol
+      POS_INFINITY: Symbol
+      attr_reader min: (Integer | Symbol)
+      attr_reader max: (Integer | Symbol)
+      def initialize: ((Integer | Symbol) min, (Integer | Symbol) max) -> void
+      def universal?: () -> bool
+      def finite?: () -> bool
+      def cardinality: () -> (Integer | Float)
+      def covers?: (untyped value) -> bool
+      def lower: () -> Numeric
+      def upper: () -> Numeric
+      def describe: (?Symbol verbosity) -> String
+      def generic_description: () -> String
+      def erase_to_rbs: () -> String
+      def top: () -> Top
+      def bot: () -> Bot
+      def dynamic: () -> Dynamic
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
     class Nominal
       attr_reader class_name: String
       attr_reader type_args: Array[Type::t]
@@ -101,6 +125,21 @@ module Rigor
       def inspect: () -> String
     end
 
+    class Difference
+      attr_reader base: Type::t
+      attr_reader removed: Type::t
+      def initialize: (Type::t base, Type::t removed) -> void
+      def describe: (?Symbol verbosity) -> String
+      def erase_to_rbs: () -> String
+      def top: () -> Top
+      def bot: () -> Bot
+      def dynamic: () -> Dynamic
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
     class Tuple
       attr_reader elements: Array[Type::t]
       def initialize: (Array[Type::t] elements) -> void
@@ -163,6 +202,17 @@ module Rigor
       def self?.nominal_of: (Module | String class_name_or_object, ?type_args: Array[Type::t]) -> Nominal
       def self?.singleton_of: (Module | String class_name_or_object) -> Singleton
       def self?.constant_of: (untyped value) -> Constant
+      def self?.difference: (Type::t base, Type::t removed) -> Difference
+      def self?.non_empty_string: () -> Difference
+      def self?.non_zero_int: () -> Difference
+      def self?.non_empty_array: (?Type::t element) -> Difference
+      def self?.non_empty_hash: (?Type::t key, ?Type::t value) -> Difference
+      def self?.integer_range: ((Integer | Symbol) min, (Integer | Symbol) max) -> IntegerRange
+      def self?.positive_int: () -> IntegerRange
+      def self?.non_negative_int: () -> IntegerRange
+      def self?.negative_int: () -> IntegerRange
+      def self?.non_positive_int: () -> IntegerRange
+      def self?.universal_int: () -> IntegerRange
       def self?.tuple_of: (*Type::t elements) -> Tuple
       def self?.hash_shape_of: (?Hash[untyped, Type::t]? pairs, **untyped options) -> HashShape
       def self?.union: (*Type::t types) -> Type::t

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Rigor contributors
@@ -160,6 +160,11 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- data/builtins/ruby_core/array.yml
+- data/builtins/ruby_core/file.yml
+- data/builtins/ruby_core/io.yml
+- data/builtins/ruby_core/numeric.yml
+- data/builtins/ruby_core/string.yml
 - exe/rigor
 - lib/rigor.rb
 - lib/rigor/analysis/check_rules.rb
@@ -169,6 +174,7 @@ files:
 - lib/rigor/analysis/runner.rb
 - lib/rigor/ast.rb
 - lib/rigor/ast/type_node.rb
+- lib/rigor/builtins/imported_refinements.rb
 - lib/rigor/cli.rb
 - lib/rigor/cli/type_of_command.rb
 - lib/rigor/cli/type_of_renderer.rb
@@ -182,6 +188,10 @@ files:
 - lib/rigor/environment/rbs_loader.rb
 - lib/rigor/inference/acceptance.rb
 - lib/rigor/inference/block_parameter_binder.rb
+- lib/rigor/inference/builtins/array_catalog.rb
+- lib/rigor/inference/builtins/method_catalog.rb
+- lib/rigor/inference/builtins/numeric_catalog.rb
+- lib/rigor/inference/builtins/string_catalog.rb
 - lib/rigor/inference/closure_escape_analyzer.rb
 - lib/rigor/inference/coverage_scanner.rb
 - lib/rigor/inference/expression_typer.rb
@@ -189,6 +199,8 @@ files:
 - lib/rigor/inference/fallback_tracer.rb
 - lib/rigor/inference/method_dispatcher.rb
 - lib/rigor/inference/method_dispatcher/constant_folding.rb
+- lib/rigor/inference/method_dispatcher/file_folding.rb
+- lib/rigor/inference/method_dispatcher/iterator_dispatch.rb
 - lib/rigor/inference/method_dispatcher/overload_selector.rb
 - lib/rigor/inference/method_dispatcher/rbs_dispatch.rb
 - lib/rigor/inference/method_dispatcher/shape_dispatch.rb
@@ -210,8 +222,10 @@ files:
 - lib/rigor/type/bot.rb
 - lib/rigor/type/combinator.rb
 - lib/rigor/type/constant.rb
+- lib/rigor/type/difference.rb
 - lib/rigor/type/dynamic.rb
 - lib/rigor/type/hash_shape.rb
+- lib/rigor/type/integer_range.rb
 - lib/rigor/type/nominal.rb
 - lib/rigor/type/singleton.rb
 - lib/rigor/type/top.rb