rigortype 0.0.3 → 0.0.4

data/lib/rigor/rbs_extended.rb

@@ -50,10 +50,19 @@ module Rigor
     # when the directive uses the `~ClassName` form, in
     # which case the engine narrows AWAY from `class_name`
     # (`Narrowing.narrow_not_class`) instead of toward it.
-    PredicateEffect = Data.define(:edge, :target_kind, :target_name, :class_name, :negative) do
+    #
+    # `refinement_type` is non-nil when the right-hand side is
+    # a kebab-case refinement name (`non-empty-string`,
+    # `lowercase-string`, …) instead of a Capitalised class
+    # name. The narrowing tier substitutes the carrier for the
+    # current local type; `class_name` is then nil and
+    # `negative` is false (refinement-form directives do not
+    # support `~T` negation in v0.0.4).
+    PredicateEffect = Data.define(:edge, :target_kind, :target_name, :class_name, :negative, :refinement_type) do
       def truthy_only? = edge == :truthy_only
       def falsey_only? = edge == :falsey_only
       def negative? = negative == true
+      def refinement? = !refinement_type.nil?
     end
 
     # Returned for `assert` / `assert-if-true` /
@@ -71,11 +80,12 @@ module Rigor
     #
     # `negative` mirrors `PredicateEffect`: true when the
     # directive uses `~ClassName` syntax.
-    AssertEffect = Data.define(:condition, :target_kind, :target_name, :class_name, :negative) do
+    AssertEffect = Data.define(:condition, :target_kind, :target_name, :class_name, :negative, :refinement_type) do
       def always? = condition == :always
       def if_truthy_return? = condition == :if_truthy_return
       def if_falsey_return? = condition == :if_falsey_return
       def negative? = negative == true
+      def refinement? = !refinement_type.nil?
     end
 
     module_function
@@ -100,14 +110,26 @@ module Rigor
       effects.uniq
     end
 
+    # The right-hand side accepts either a Capitalised class
+    # name (with optional `~` negation, optional `::` prefix,
+    # qualified names) OR a kebab-case refinement payload
+    # routed through `Builtins::ImportedRefinements::Parser`
+    # (bare names, `name[T]`, `name<min, max>`). The two arms
+    # share the same overall directive shape; the parser
+    # detects which form matched by looking at the `class_name`
+    # vs `refinement` capture groups.
     PREDICATE_DIRECTIVE_PATTERN = /
       \A
       rigor:v1:(?<directive>predicate-if-(?:true|false))
       \s+
       (?<target>self|[a-z_][a-zA-Z0-9_]*)
       \s+is\s+
-      (?<negation>~?)
-      (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
+      (?:
+        (?<negation>~?)
+        (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
+        |
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+      )
       \s*
       \z
     /x
@@ -119,16 +141,18 @@ module Rigor
 
       directive = match[:directive].to_s
       target = match[:target].to_s
-      class_name = match[:class_name].to_s.sub(/\A::/, "")
       edge = directive == "predicate-if-true" ? :truthy_only : :falsey_only
-      target_kind = target == "self" ? :self : :parameter
-      target_name = target == "self" ? :self : target.to_sym
+      target_kind, target_name = target_fields(target)
+      class_name, refinement_type, negative = resolve_directive_rhs(match)
+      return nil if class_name.nil? && refinement_type.nil?
+
       PredicateEffect.new(
         edge: edge,
         target_kind: target_kind,
         target_name: target_name,
         class_name: class_name,
-        negative: match[:negation].to_s == "~"
+        negative: negative,
+        refinement_type: refinement_type
       )
     end
 
@@ -157,8 +181,12 @@ module Rigor
       \s+
       (?<target>self|[a-z_][a-zA-Z0-9_]*)
       \s+is\s+
-      (?<negation>~?)
-      (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
+      (?:
+        (?<negation>~?)
+        (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
+        |
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+      )
       \s*
       \z
     /x
@@ -180,18 +208,55 @@ module Rigor
       return nil if condition.nil?
 
       target = match[:target].to_s
-      class_name = match[:class_name].to_s.sub(/\A::/, "")
-      target_kind = target == "self" ? :self : :parameter
-      target_name = target == "self" ? :self : target.to_sym
+      target_kind, target_name = target_fields(target)
+      class_name, refinement_type, negative = resolve_directive_rhs(match)
+      return nil if class_name.nil? && refinement_type.nil?
+
       AssertEffect.new(
         condition: condition,
         target_kind: target_kind,
         target_name: target_name,
         class_name: class_name,
-        negative: match[:negation].to_s == "~"
+        negative: negative,
+        refinement_type: refinement_type
       )
     end
 
+    # Resolves the `class_name` / `refinement` alternation in
+    # the assert / predicate directive patterns. Returns
+    # `[class_name, refinement_type, negative]`:
+    #
+    # - Class-name arm matched: `class_name` is the resolved
+    #   string (leading `::` stripped), `refinement_type` is
+    #   nil, `negative` reflects the optional `~` prefix.
+    # - Refinement arm matched: `class_name` is nil,
+    #   `refinement_type` is the resolved `Rigor::Type`,
+    #   `negative` is `false` (refinement-form directives do
+    #   not support `~` negation in v0.0.4).
+    # - Refinement payload unparseable: returns
+    #   `[nil, nil, false]` so callers can drop the directive
+    #   silently (fail-soft policy).
+    def resolve_directive_rhs(match)
+      class_capture = match[:class_name]
+      return [class_capture.to_s.sub(/\A::/, ""), nil, match[:negation].to_s == "~"] if class_capture
+
+      refinement_capture = match[:refinement]
+      return [nil, nil, false] if refinement_capture.nil?
+
+      type = Builtins::ImportedRefinements.parse(refinement_capture)
+      return [nil, nil, false] if type.nil?
+
+      [nil, type, false]
+    end
+
+    def target_fields(target)
+      if target == "self"
+        %i[self self]
+      else
+        [:parameter, target.to_sym]
+      end
+    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
@@ -238,11 +303,20 @@ module Rigor
       nil
     end
 
+    # The trailing payload supports the full refinement
+    # grammar in `Builtins::ImportedRefinements::Parser` —
+    # bare kebab-case names plus parameterised forms like
+    # `non-empty-array[Integer]`, `non-empty-hash[Symbol,
+    # Integer]`, and `int<5, 10>`. The directive head is
+    # consumed by the regex; the rest is forwarded to the
+    # refinement parser. Anything the parser cannot resolve
+    # falls back to nil so the call site keeps the
+    # RBS-declared return type.
     RETURN_DIRECTIVE_PATTERN = /
       \A
       rigor:v1:return:
       \s+
-      (?<refinement>[a-z][a-z0-9-]*)
+      (?<payload>\S(?:.*\S)?)
       \s*
       \z
     /x
@@ -252,7 +326,84 @@ module Rigor
       match = RETURN_DIRECTIVE_PATTERN.match(string)
       return nil if match.nil?
 
-      Builtins::ImportedRefinements.lookup(match[:refinement])
+      Builtins::ImportedRefinements.parse(match[:payload])
+    end
+
+    # Returned for `rigor:v1:param: <name> <refinement>`. The
+    # parameter name is a Ruby identifier (Symbol); the type
+    # is any `Rigor::Type` the refinement parser resolves
+    # (bare kebab-case name, parameterised form, or `int<...>`
+    # range — the same grammar the `return:` directive
+    # accepts).
+    ParamOverride = Data.define(:param_name, :type)
+
+    # Reads every `rigor:v1:param: <name> <refinement>`
+    # directive off `RBS::Definition::Method#annotations` and
+    # returns the resolved `ParamOverride` list. Annotations
+    # the parser cannot resolve (typo, unknown refinement, no
+    # `param:` directive at all) are silently dropped — the
+    # call site keeps the RBS-declared parameter type for
+    # those parameters. The reader accepts a nil method
+    # definition so call sites can pass through optional
+    # method lookups without a guard.
+    #
+    # Example annotation in an RBS file:
+    #
+    #   class Slug
+    #     %a{rigor:v1:param: id is non-empty-string}
+    #     def normalise: (::String id) -> String
+    #   end
+    #
+    # The RBS-declared type of `id` is `String`. The override
+    # tightens it to `non-empty-string` for argument-check
+    # purposes; passing a too-wide `Nominal[String]` argument
+    # is flagged as an argument-type mismatch at the call
+    # site.
+    def read_param_type_overrides(method_def)
+      return [] if method_def.nil?
+
+      annotations = method_def.annotations
+      return [] if annotations.nil? || annotations.empty?
+
+      annotations.filter_map { |annotation| parse_param_annotation(annotation.string) }
+    end
+
+    # Convenience reader for call sites that want to look up
+    # a single override by parameter name. Returns a frozen
+    # Hash<Symbol, Rigor::Type>; missing keys mean "use the
+    # RBS-declared type". Callers MUST treat the hash as
+    # read-only.
+    def param_type_override_map(method_def)
+      read_param_type_overrides(method_def).to_h { |o| [o.param_name, o.type] }.freeze
+    end
+
+    # The `is` glue word is optional so authors can write
+    # either `param: id is non-empty-string` (consistent with
+    # the existing `assert` / `predicate-if-*` directives) or
+    # the terser `param: id non-empty-string`. The trailing
+    # payload accepts the full refinement grammar in
+    # `Builtins::ImportedRefinements::Parser`.
+    PARAM_DIRECTIVE_PATTERN = /
+      \A
+      rigor:v1:param:
+      \s+
+      (?<param>[a-z_][a-zA-Z0-9_]*)
+      \s+
+      (?:is\s+)?
+      (?<payload>\S(?:.*\S)?)
+      \s*
+      \z
+    /x
+    private_constant :PARAM_DIRECTIVE_PATTERN
+
+    def parse_param_annotation(string)
+      match = PARAM_DIRECTIVE_PATTERN.match(string)
+      return nil if match.nil?
+
+      type = Builtins::ImportedRefinements.parse(match[:payload])
+      return nil if type.nil?
+
+      ParamOverride.new(param_name: match[:param].to_sym, type: type)
     end
   end
 end

data/lib/rigor/type/combinator.rb

@@ -11,6 +11,8 @@ require_relative "tuple"
 require_relative "hash_shape"
 require_relative "union"
 require_relative "difference"
+require_relative "refined"
+require_relative "intersection"
 
 module Rigor
   module Type
@@ -133,6 +135,65 @@ module Rigor
         )
       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]`.
@@ -185,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/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

data/lib/rigor/type/refined.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # `Refined[base, predicate_id]` — predicate-subset half of
+    # the OQ3 refinement-carrier strategy
+    # ([ADR-3](docs/adr/3-type-representation.md), Working
+    # Decision Option C). Sibling of `Type::Difference`, which
+    # carries the point-removal half.
+    #
+    #   lowercase-string = Refined[Nominal[String], :lowercase]
+    #   uppercase-string = Refined[Nominal[String], :uppercase]
+    #   numeric-string   = Refined[Nominal[String], :numeric]
+    #
+    # The carrier wraps a base type and a `predicate_id` Symbol
+    # drawn from {PREDICATES}. The recogniser is invoked at
+    # constant-fold and acceptance time over a `Constant<base>`
+    # value; for non-Constant receivers the carrier is a marker
+    # the catalog tier consults to project `String#downcase` /
+    # `String#upcase` (etc.) into the matching refinement.
+    #
+    # Display routes through {CANONICAL_NAMES}: registered
+    # `(base_class_name, predicate_id)` pairs print in their
+    # kebab-case spelling (`lowercase-string`); unregistered
+    # combinations fall back to the `base & predicate?` operator
+    # form per
+    # [`type-operators.md`](docs/type-specification/type-operators.md).
+    #
+    # Construction MUST go through `Type::Combinator.refined` /
+    # the per-name factories (`Combinator.lowercase_string`,
+    # `Combinator.uppercase_string`, `Combinator.numeric_string`).
+    # Direct `.new` is an internal escape hatch for tests and
+    # combinator's own implementation.
+    class Refined
+      attr_reader :base, :predicate_id
+
+      def initialize(base, predicate_id)
+        raise ArgumentError, "predicate_id must be a Symbol" unless predicate_id.is_a?(Symbol)
+
+        @base = base
+        @predicate_id = predicate_id
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        named = canonical_name
+        return named if named
+
+        "#{base.describe(verbosity)} & #{predicate_id}?"
+      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?(Refined) && base == other.base && predicate_id == other.predicate_id
+      end
+      alias eql? ==
+
+      def hash
+        [Refined, base, predicate_id].hash
+      end
+
+      def inspect
+        "#<Rigor::Type::Refined #{describe(:short)}>"
+      end
+
+      # Recognises a Ruby value against this carrier's
+      # predicate. The trinary return is intentional: `true` /
+      # `false` when the predicate registry decides, `nil`
+      # when the predicate is unknown to the registry, so
+      # callers (today {Inference::Acceptance}) can fall
+      # through to gradual-mode `:maybe`.
+      # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
+      def matches?(value)
+        recogniser = PREDICATES[predicate_id]
+        return nil if recogniser.nil?
+
+        !!recogniser.call(value)
+      end
+      # rubocop:enable Style/ReturnNilInPredicateMethodDefinition
+
+      # `predicate_id => recogniser` table. The recogniser is
+      # called with a Ruby value (typically the inner `value`
+      # of a `Constant`) and returns truthy when the value
+      # satisfies the predicate. The recogniser MUST be total
+      # (return false rather than raise) over arbitrary input,
+      # so callers can pass any `Constant#value` without a
+      # type-prefilter.
+      #
+      # Plugin-contributed predicates land here once ADR-2 is
+      # in flight; today the table is closed over the v0.0.4
+      # built-in catalogue.
+      #
+      # Recogniser policy:
+      #
+      # - `:numeric` is deliberately conservative — only decimal
+      #   integer and plain-decimal-fraction strings are
+      #   recognised, mirroring `imported-built-in-types.md`'s
+      #   "Rigor's numeric-string predicate" wording. Looser
+      #   forms (scientific, hex, rational) MAY join later
+      #   without breaking the registry contract.
+      # - `:decimal_int` is "what `Integer(s, 10)` would parse
+      #   without remainder" — one or more decimal digits,
+      #   optional leading sign, no whitespace, no fractional
+      #   tail.
+      # - `:octal_int` and `:hex_int` REQUIRE their conventional
+      #   prefix (`0o` / `0O` / leading `0` for octal; `0x` /
+      #   `0X` for hex) so the predicate is disjoint from
+      #   `:decimal_int`. A bare `"755"` is decimal-int-string,
+      #   not octal-int-string. This matches the typical user
+      #   intent — a refinement marks a string that "looks like
+      #   octal", not "happens to be base-8 valid".
+      NUMERIC_STRING_PATTERN = /\A-?\d+(?:\.\d+)?\z/
+      DECIMAL_INT_STRING_PATTERN = /\A-?\d+\z/
+      OCTAL_INT_STRING_PATTERN = /\A-?(?:0[oO][0-7]+|0[0-7]+)\z/
+      HEX_INT_STRING_PATTERN = /\A-?0[xX][0-9a-fA-F]+\z/
+      private_constant :NUMERIC_STRING_PATTERN, :DECIMAL_INT_STRING_PATTERN,
+                       :OCTAL_INT_STRING_PATTERN, :HEX_INT_STRING_PATTERN
+
+      PREDICATES = {
+        lowercase: ->(v) { v.is_a?(String) && v == v.downcase },
+        uppercase: ->(v) { v.is_a?(String) && v == v.upcase },
+        numeric: ->(v) { v.is_a?(String) && NUMERIC_STRING_PATTERN.match?(v) },
+        decimal_int: ->(v) { v.is_a?(String) && DECIMAL_INT_STRING_PATTERN.match?(v) },
+        octal_int: ->(v) { v.is_a?(String) && OCTAL_INT_STRING_PATTERN.match?(v) },
+        hex_int: ->(v) { v.is_a?(String) && HEX_INT_STRING_PATTERN.match?(v) }
+      }.freeze
+
+      # Maps `[base_class_name, predicate_id]` pairs to their
+      # kebab-case canonical name. Registered shapes print
+      # through `describe`; unregistered combinations fall back
+      # to the operator form.
+      CANONICAL_NAMES = {
+        ["String", :lowercase] => "lowercase-string",
+        ["String", :uppercase] => "uppercase-string",
+        ["String", :numeric] => "numeric-string",
+        ["String", :decimal_int] => "decimal-int-string",
+        ["String", :octal_int] => "octal-int-string",
+        ["String", :hex_int] => "hex-int-string"
+      }.freeze
+      private_constant :CANONICAL_NAMES
+
+      private
+
+      def canonical_name
+        return nil unless base.is_a?(Nominal)
+
+        CANONICAL_NAMES[[base.class_name, predicate_id]]
+      end
+    end
+  end
+end

data/lib/rigor/type.rb

@@ -21,5 +21,7 @@ require_relative "type/tuple"
 require_relative "type/hash_shape"
 require_relative "type/union"
 require_relative "type/difference"
+require_relative "type/refined"
+require_relative "type/intersection"
 require_relative "type/accepts_result"
 require_relative "type/combinator"