rigortype 0.0.2 → 0.0.4

data/lib/rigor/type/combinator.rb

@@ -6,9 +6,13 @@ 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"
+require_relative "refined"
+require_relative "intersection"
 
 module Rigor
   module Type
@@ -20,7 +24,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 +69,131 @@ 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
+
+      # Predicate-subset refinement carrier (ADR-3 OQ3 Option C,
+      # second half). Use `lowercase_string` /
+      # `uppercase_string` / `numeric_string` for the imported
+      # built-in shapes; raw `refined(base, predicate_id)` for
+      # ad-hoc refinements introduced by an `RBS::Extended`
+      # annotation or a plugin-contributed predicate.
+      def refined(base, predicate_id)
+        Refined.new(base, predicate_id)
+      end
+
+      def lowercase_string
+        Refined.new(nominal_of("String"), :lowercase)
+      end
+
+      def uppercase_string
+        Refined.new(nominal_of("String"), :uppercase)
+      end
+
+      def numeric_string
+        Refined.new(nominal_of("String"), :numeric)
+      end
+
+      def decimal_int_string
+        Refined.new(nominal_of("String"), :decimal_int)
+      end
+
+      def octal_int_string
+        Refined.new(nominal_of("String"), :octal_int)
+      end
+
+      def hex_int_string
+        Refined.new(nominal_of("String"), :hex_int)
+      end
+
+      # Normalised intersection. Flattens nested Intersections,
+      # drops `Top` members, collapses to `Bot` if any member is
+      # `Bot`, deduplicates structurally-equal members, sorts the
+      # survivors by `describe(:short)`, and collapses 0-/1-member
+      # results so a degenerate intersection never reaches the
+      # carrier. See ADR-3 OQ3 for the rationale; the lattice
+      # algebra is in
+      # [`value-lattice.md`](docs/type-specification/value-lattice.md).
+      def intersection(*members)
+        collapse_intersection(normalised_intersection_members(members))
+      end
+
+      # `non-empty-lowercase-string` = non-empty-string ∩
+      # lowercase-string. Composes the point-removal half
+      # (`Difference[String, ""]`) with the predicate-subset half
+      # (`Refined[String, :lowercase]`). Both members erase to
+      # `String` so the carrier's RBS erasure is unambiguous.
+      def non_empty_lowercase_string
+        intersection(non_empty_string, lowercase_string)
+      end
+
+      def non_empty_uppercase_string
+        intersection(non_empty_string, uppercase_string)
+      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]`.
@@ -117,6 +246,35 @@ module Rigor
           end
         end
 
+        # Symmetric counterparts to the Union normalisers. The
+        # absorbing element is `Bot` (anything intersected with
+        # nothing is nothing) and the identity element is `Top`
+        # (intersecting with the universal type is a no-op).
+        def normalised_intersection_members(types)
+          flattened = []
+          types.each { |t| flatten_intersection_into(flattened, t) }
+          return [bot] if flattened.any?(Bot)
+
+          flattened.reject! { |t| t.is_a?(Top) }
+          unique_members(flattened)
+        end
+
+        def collapse_intersection(types)
+          case types.size
+          when 0 then top
+          when 1 then types.first
+          else Intersection.new(sort_members(types))
+          end
+        end
+
+        def flatten_intersection_into(acc, type)
+          if type.is_a?(Intersection)
+            type.members.each { |m| flatten_intersection_into(acc, m) }
+          else
+            acc << type
+          end
+        end
+
         def resolve_class_name(class_name_or_object)
           name =
             case class_name_or_object

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/intersection.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # `Intersection[M1, M2, …]` — value set is the meet of every
+    # member's value set. The carrier composes refinements that
+    # share a base, in particular the catalogued
+    # `non-empty-lowercase-string` (= `Difference[String, ""] &
+    # Refined[String, :lowercase]`) and
+    # `non-empty-uppercase-string` shapes from
+    # [`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md).
+    # See [ADR-3](docs/adr/3-type-representation.md) for the
+    # OQ3 working decision and the rationale for keeping
+    # Intersection a thin wrapper rather than per-shape carriers.
+    #
+    # Construction MUST go through `Type::Combinator.intersection`
+    # (or the per-name factories
+    # `Combinator.non_empty_lowercase_string` /
+    # `Combinator.non_empty_uppercase_string`). The factory:
+    #
+    # - flattens nested intersections,
+    # - drops `Top` members (Top is the identity of intersection),
+    # - collapses to `Bot` if any member is `Bot` (Bot is absorbing),
+    # - deduplicates structurally-equal members,
+    # - sorts the surviving members by `describe(:short)` so two
+    #   structurally-equal intersections built in different orders
+    #   compare equal,
+    # - returns `Top` for the empty intersection,
+    # - returns the lone member for a 1-element intersection (so
+    #   the carrier is never inhabited by a degenerate single-member
+    #   shape).
+    #
+    # Direct `.new` callers MUST pass an already-normalised member
+    # list and are expected to be tests or the combinator itself.
+    class Intersection
+      attr_reader :members
+
+      def initialize(members)
+        @members = members.dup.freeze
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        named = canonical_name
+        return named if named
+
+        members.map { |m| m.describe(verbosity) }.join(" & ")
+      end
+
+      # An intersection of refinements over the same base type
+      # erases to that base. We use the first member's erasure
+      # because the v0.0.4 catalogue (`non-empty-lowercase-string`
+      # etc.) is restricted to same-base composition; richer
+      # cross-base intersections will need a stricter erasure
+      # rule (likely "lowest common ancestor" via the inference
+      # engine's class hierarchy).
+      def erase_to_rbs
+        members.first.erase_to_rbs
+      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?(Intersection) && members == other.members
+      end
+      alias eql? ==
+
+      def hash
+        [Intersection, members].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Intersection #{describe(:short)}>"
+      end
+
+      private
+
+      # Maps a structurally-recognised composite shape to its
+      # kebab-case canonical name. 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)).
+      #
+      # Detection is order-independent — `Combinator.intersection`
+      # sorts the canonical member list, but reading the registry
+      # the other way around (a user-authored Intersection built
+      # in any order) MUST still print in its canonical spelling.
+      def canonical_name
+        return nil unless members.size == 2
+
+        bases = members.map { |m| canonical_role(m) }.compact
+        return nil unless bases.size == 2
+
+        roles = bases.sort
+        case roles
+        when %w[lowercase non_empty_string] then "non-empty-lowercase-string"
+        when %w[non_empty_string uppercase] then "non-empty-uppercase-string"
+        end
+      end
+
+      # Returns a stable role tag for the recognised composite
+      # members so `canonical_name` can pattern-match on a sorted
+      # role pair regardless of construction order. Returns nil
+      # when the member is not part of any catalogued composite —
+      # any nil contribution disqualifies the canonical-name path
+      # and the operator-form fallback kicks in.
+      def canonical_role(member)
+        case member
+        when Difference
+          "non_empty_string" if member == Type::Combinator.non_empty_string
+        when Refined
+          case member
+          when Type::Combinator.lowercase_string then "lowercase"
+          when Type::Combinator.uppercase_string then "uppercase"
+          end
+        end
+      end
+    end
+  end
+end