plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/conjunction.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Plumb
+  # The runtime shared by {Plumb::And} (sequential composition) and
+  # {Plumb::Intersection} (the lattice meet). Both execute as `left` then `right`;
+  # they differ only in how types flow, which each class defines.
+  #
+  # They must be separate nodes because the two roles disagree about identity: a
+  # COMPOSITION is a morphism, identified by what it PRODUCES (like a Function),
+  # while an INTERSECTION is a type, identified by itself and subject to the meet
+  # rule (`(a ∧ b) <= c` when either conjunct is). Applying the meet rule to a
+  # composition is unsound — it makes `String >> (String -> Integer)` a subtype of
+  # String as well as Integer, two disjoint types.
+  module Conjunction
+    # An Intersection exactly when neither side changes the value (a refinement:
+    # both sides narrow one value, order irrelevant); otherwise a pipeline whose
+    # ends differ, an And.
+    #
+    # The single decision point — every construction site routes through here, so
+    # the distinction is settled once rather than re-derived from
+    # `#value_preserving?` at each use site.
+    #
+    # @param left [Composable]
+    # @param right [Composable]
+    # @return [Intersection, And]
+    def self.build(left, right)
+      if Plumb::Subtyping.value_preserving?(left) && Plumb::Subtyping.value_preserving?(right)
+        Intersection.new(left, right)
+      else
+        And.new(left, right)
+      end
+    end
+
+    attr_reader :children, :input_type, :output_type
+
+    def call(result)
+      result.map(@left).map(@right)
+    end
+
+    # Rebuilds by RECLASSIFYING: a rewrite that swaps a check for a conversion turns
+    # a meet into a composition, and preserving the class would leave an Intersection
+    # lying about #value_preserving?, which every reduction gates on.
+    # @see Plumb::NodeMapper
+    def with_children(children) = Conjunction.build(children[0], children[1])
+
+    private def _inspect
+      %((#{@left.inspect} >> #{@right.inspect}))
+    end
+  end
+end

data/lib/plumb/constraint.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'plumb/composable'
+
+module Plumb
+  class Constraint
+    include Composable
+
+    # Sentinel returned by `merge_matchers`/`intersect_ranges` when two same-kind
+    # matchers have a PROVABLY-EMPTY overlap (disjoint Ranges, empty Set
+    # intersection). Distinct from `nil`, which means "not the same knowable kind,
+    # or an incomputable overlap — leave the two matchers stacked". Callers map
+    # EMPTY to `Types::Never`, so `Integer[0..5][10..]` == `Integer[0..5] & Integer[10..]`
+    # == `Types::Never` (see .narrow and Subtyping.intersect_constraints).
+    EMPTY = ::Object.new
+    def EMPTY.inspect = 'Plumb::Constraint::EMPTY'
+    EMPTY.freeze
+
+    # Matcher kinds whose `#===` is just `#==` — they match exactly ONE value.
+    # Two distinct ones are therefore provably disjoint, and as a `#>>` consumer
+    # one accepts only its own value. Deliberately excludes Module/Range/Regexp/
+    # Set/proc: their `#===` is a type, membership or pattern test that matches
+    # many values (and `Set#===` is `#include?` on Ruby >= 3.1).
+    LITERAL_MATCHERS = [::String, ::Symbol, ::Numeric, ::TrueClass, ::FalseClass, ::NilClass].freeze
+
+    # The matcher-level form of #literal? for normalization callers that do not
+    # yet have a Constraint. Prefer #literal? on an existing Constraint.
+    #
+    # @param matcher [#===]
+    # @return [Boolean] whether `matcher` matches a single value by equality
+    def self.literal_matcher?(matcher) = SemanticMatcher.singleton?(matcher)
+
+    attr_reader :children, :base, :matcher
+
+    # @param matcher [#===] the value/type/predicate to match against
+    # @param base [Composable, nil] the type this matcher *refines*. `nil` for a
+    #   root type matcher (eg. `Types::Integer` is `Constraint(::Integer)`); set for a
+    #   refinement built via `#[]`/`#match`/`#check` (eg. `Integer[1..10]` is
+    #   `Constraint(1..10, base: Types::Integer)`). Carrying the base lets a matcher
+    #   answer subtyping locally — it is a subtype of whatever its base is — so no
+    #   `And` wrapper (or transparency flag) is needed to preserve the base type.
+    def initialize(matcher = Undefined, base: nil, error: nil, label: nil)
+      raise ParseError, 'matcher must respond to #===' unless matcher.respond_to?(:===)
+
+      raise_if_incompatible!(base, matcher) if base
+
+      @matcher = matcher
+      @matcher_node = SemanticMatcher.wrap(matcher)
+      @base = base
+      @error = error.nil? ? build_error(matcher) : (error % matcher)
+      @label = matcher.is_a?(Class) ? matcher.inspect : "Constraint(#{label || @matcher.inspect})"
+      @children = [matcher].freeze
+      freeze
+    end
+
+    # Smart refinement constructor: builds `Constraint.new(matcher, base:)`, but
+    # when both `base` (a Constraint) and `matcher` are the same kind of knowable
+    # matcher (Ranges or Sets), it INTERSECTS them into one over `base`'s own base
+    # rather than stacking two checks — so `Integer[0..100][10..]` is
+    # `Integer[10..100]`, `Integer[Set[1,2,3]][Set[2,3,4]]` is `Integer[Set[2,3]]`,
+    # and `Integer[0..100] >> Integer[0..]` reduces to `Integer[0..100]`. Other
+    # matchers stack as before.
+    def self.narrow(base, matcher)
+      if base.is_a?(Constraint)
+        merged = merge_matchers(base.matcher, matcher)
+        return Types::Never if merged.equal?(EMPTY) # provably-empty overlap ⇒ bottom
+        return narrow(base.base, merged) if merged # recurse: base.base may be a type gate
+      end
+      new(matcher, base:)
+    end
+
+    # Intersection of two knowable matchers of the same kind. Returns the merged
+    # matcher on a non-empty overlap, `EMPTY` when the overlap is provably empty
+    # (disjoint Ranges / empty Set intersection — callers reduce it to Never), or
+    # `nil` to not merge (different kinds, or an incomputable Range overlap — leave
+    # the two matchers stacked). Public because AttributeValueMatch narrowing
+    # reuses it (see Subtyping) — an attribute constraint intersects its Range/Set
+    # values just like a Constraint.
+    def self.merge_matchers(a, b)
+      merged = SemanticMatcher.merge(a, b)
+      return EMPTY if merged.empty?
+      return merged.node.raw if merged.merged?
+
+      nil
+    end
+
+    # As the consumer of a `left >> self` chain:
+    #   - a refinement (has a base), a Class/Module gate, or a literal matcher
+    #     accepts exactly what it validates — itself — so `Integer >>
+    #     Integer[1..10]` and `Any[5] >> Any[6]` are correctly rejected (narrow
+    #     with `#[]` instead), and the default `#accepted_type` (its resolved
+    #     input) is `self`;
+    #   - a bare pattern matcher (regex/range/set/proc with no base) narrows
+    #     arbitrary input over a domain it cannot name, so it reports Any and opts
+    #     out of the check.
+    def input_type
+      return self if base || @matcher_node.nominal? || literal?
+
+      Types::Any
+    end
+
+    # Whether this constraint matches a SINGLE value, by equality — so two
+    # distinct ones are provably disjoint (see Subtyping#literal_value).
+    def literal? = @matcher_node.singleton?
+
+    # @return [Boolean] whether the base and matcher are safe to deduplicate
+    def idempotent? = @base.nil? || @base.idempotent?
+
+    # A converting base runs before the matcher, so this constraint consumes what
+    # the base accepts. Pure refinements accept themselves.
+    # @return [Composable]
+    def accepted_type
+      return self unless @base && !Plumb::Subtyping.value_preserving?(@base)
+
+      Plumb::Subtyping.accepted_type(@base)
+    end
+
+    # Projects a matcher over a conversion onto the narrowed output type. Without
+    # this, subtype checks would treat the node as consuming the value it produces.
+    # @return [Composable]
+    def subtype_identity
+      return self if @base.nil? || Plumb::Subtyping.value_preserving?(@base)
+
+      produced = Plumb::Subtyping.resolved_output(@base)
+      produced.equal?(@base) ? self : Constraint.narrow(produced, @matcher)
+    end
+
+    # A constraint may wrap a converting base; treating it as a pure filter would
+    # let reductions discard that conversion.
+    # @return [Boolean] whether the base and matcher preserve the input value
+    def value_preserving? = @base.nil? || Plumb::Subtyping.value_preserving?(@base)
+
+    # Structural subtyping. A matcher describes the set `base ∩ {x | matcher === x}`
+    # (base = everything when nil). `self <= other` when self's set is contained in
+    # each of other's conjuncts: within other's base (if any) AND within other's
+    # matcher. Against a non-matcher type, a refinement is a subtype of whatever
+    # its base is (like AttributeValueMatch).
+    def subtype_of?(other)
+      return true if self == other
+
+      if other.is_a?(Constraint)
+        within_base = other.base.nil? || Plumb::Subtyping.subtype?(self, other.base)
+        return true if within_base && within_matcher?(other.matcher)
+
+        # `self` is `base ∩ {matcher}` — a subset of `base` — so whenever the
+        # base alone is a subtype of `other`, so is `self`. This is the same
+        # fallback the non-Constraint branch below uses; it belongs here too
+        # because base types (`Types::String`, `Types::Date`) ARE Constraints,
+        # and `within_matcher?` can't peel a transparent base (a Metadata/Policy
+        # wrapper, eg. `String.metadata(...).present`) to see the guarantee.
+        base ? Plumb::Subtyping.subtype?(base, other) : false
+      elsif base
+        Plumb::Subtyping.subtype?(base, other)
+      else
+        false
+      end
+    end
+
+    # Is every value self describes matched by `m`? True if self's own matcher is
+    # within `m`, or self's base already guarantees it (eg. `Integer.check {}` is
+    # within `::Integer` because its base is Integer, even though its proc matcher
+    # tells us nothing).
+    protected def within_matcher?(m)
+      Plumb::Subtyping.atomic_subtype?(matcher, m) ||
+        (base.is_a?(Constraint) && base.within_matcher?(m))
+    end
+
+    # Identity label for matchers without structural equality.
+    protected def label = @label
+
+    # Compares matchers and bases. Fresh Procs lack structural equality, so Proc
+    # matchers use their caller-supplied label as stable identity.
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.instance_of?(self.class) && other.base == base
+
+      if matcher.is_a?(::Proc)
+        other.matcher.is_a?(::Proc) && other.label == label
+      else
+        other.matcher == matcher
+      end
+    end
+
+    def call(result)
+      # Only the base can invalidate the incoming result (callers — map/Or/resolve
+      # — always pass a valid one), so the `valid?` short-circuit is only needed
+      # when there IS a base. Root constraints skip straight to the matcher check,
+      # like a flat leaf. Reading @base directly (not the #base reader) also skips
+      # a dispatch on this hot path.
+      if @base
+        result = @base.call(result)
+        return result unless result.valid?
+      end
+
+      @matcher === result.value ? result : result.invalid!(errors: @error)
+    end
+
+    private
+
+    # A refinement whose matcher can never match a value of the base is a
+    # contradiction — an empty type, almost always a mistake — so reject it at
+    # build time (eg. `Types::String[1..20]`: no String is in an integer range).
+    # Only checked for matchers whose domain is knowable (Class/Range/Regexp/
+    # primitive literal); procs and custom `#===` objects are opaque, so allowed.
+    def raise_if_incompatible!(base, matcher)
+      base_types = Plumb.resolve_base_types(base)
+      return if base_types.empty? # unknown base (eg. a Data schema) — allow
+      overlap = Relation.any(base_types.map { |klass| matcher_may_match_relation(matcher, klass) })
+      return unless overlap.disproven?
+
+      raise Plumb::TypeError,
+            "cannot refine #{base.inspect} with #{matcher.inspect}: " \
+            "no #{base_types.map(&:inspect).join(' / ')} value can match it"
+    end
+
+    # Attempts to prove whether `matcher` overlaps a nominal domain. Unknown is
+    # intentionally accepted by the constructor and retained as a runtime check.
+    # @return [Relation]
+    def matcher_may_match_relation(matcher, klass)
+      SemanticMatcher.wrap(matcher).overlap(SemanticMatcher.wrap(klass))
+    end
+
+    def _inspect
+      return @label unless base
+
+      "#{base.inspect}[#{@matcher.inspect}]"
+    end
+
+    def build_error(matcher)
+      SemanticMatcher.error_message(matcher)
+    end
+  end
+end

data/lib/plumb/covariant_fusion.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Plumb
+  # MAP FUSION for covariant containers — the second functor law as a rewrite rule.
+  # `Array[_]`, `Tuple[…]`, `Hash[K, _]` and `Stream[_]` are covariant functors, so
+  # mapping `f` then `g` is mapping `f >> g`:
+  #
+  #   Array[f] >> Array[g]  ==  Array[f >> g]
+  #
+  # The left traverses twice and materialises an intermediate copy; the right once. On
+  # a 50-element Array that is ~28% less time and 6 fewer allocations, growing with the
+  # collection. Hooked into `#fuse_with`, the container-level counterpart of
+  # {Plumb::Function}'s transform fusion.
+  #
+  # SOUNDNESS. Carries its OWN proof rather than trusting the caller's: `#>>`
+  # type-checks the containers first but `#/` deliberately does not, and both reach
+  # here. Every element pair must be provably composable.
+  #
+  # That guard is what keeps ERROR behaviour intact — the one thing fusion could
+  # change. Two passes report stage by stage (a first-stage failure means the second
+  # never runs), while one pass could surface a second-stage error for element 2
+  # beside a first-stage error for element 1. A provable boundary means the right
+  # element cannot reject what the left produced, so the two agree. An unprovable one
+  # (an opaque `#check`, a narrowing refinement) simply does not fuse.
+  module CovariantFusion
+    # @param other [Composable]
+    # @return [Composable, nil] the fused container, or nil to leave the pair alone
+    def fuse_with(other)
+      return nil unless self.class == other.class
+      return nil if children.empty? || children.size != other.children.size
+
+      pairs = children.zip(other.children)
+      return nil unless pairs.all? { |mine, theirs| fusable_boundary?(mine, theirs) }
+
+      with_children(pairs.map { |mine, theirs| mine >> theirs })
+    end
+
+    # Mirrors Function#fuse_with's check, using the same memoized projections.
+    private def fusable_boundary?(mine, theirs)
+      Plumb::Subtyping.subtype?(
+        Plumb::Subtyping.resolved_output(mine),
+        Plumb::Subtyping.accepted_type(theirs)
+      )
+    end
+  end
+end

data/lib/plumb/decorator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'plumb/node_mapper'
+
 module Plumb
   # A class to help decorate all or some types in a
   # type composition.
@@ -12,6 +14,15 @@ module Plumb
   #       type
   #     end
   #   end
+  #
+  # The block is called on EVERY node, bottom-up: sub-types are visited (and possibly
+  # replaced) before the block sees the node itself. Returning a node unchanged is a
+  # no-op, and an unchanged subtree comes back as the identical object.
+  #
+  # Traversal is {Plumb::NodeMapper}'s, so it reaches a record's fields, a container's
+  # element type and the inside of a Metadata / Policy / #as_node wrapper. It stops at
+  # a Constraint's base (rebuilding one would drop a custom `#check` message) and at a
+  # Deferred (forcing it would loop on a self-referential type).
   class Decorator
     def self.call(type, &block)
       new(block).visit(type)
@@ -24,32 +35,11 @@ module Plumb
     # @param type [Composable]
     # @return [Composable]
     def visit(type)
-      type = case type
-             when And
-               left, right = visit_children(type)
-               And.new(left, right)
-             when Or
-               left, right = visit_children(type)
-               Or.new(left, right)
-             when Not
-               child = visit_children(type).first
-               Not.new(child, errors: type.errors)
-             when Policy
-               child = visit_children(type).first
-               Policy.new(type.policy_name, type.arg, child)
-             else
-               type
-             end
-
-      decorate(type)
+      decorate(NodeMapper.map(type) { |child| visit(child) })
     end
 
     private
 
-    def visit_children(type)
-      type.children.map { |child| visit(child) }
-    end
-
     def decorate(type)
       @block.call(type)
     end

data/lib/plumb/deferred.rb

@@ -13,14 +13,23 @@ module Plumb
       # freeze
     end
 
+    # Deferred nodes use identity equality to avoid materializing recursive types.
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other) = equal?(other)
+
     def call(result)
-      cached_type.call(result)
+      type.call(result)
     end
 
-    private def cached_type
+    def type
       @lock.synchronize do
-        @cached_type = @definition.call
-        self.define_singleton_method(:cached_type) do
+        @cached_type ||= @definition.call
+        # Release the definition closure: it can capture large scopes (eg. a
+        # codec rewriter and the type graph it walked) that would otherwise
+        # stay reachable for the life of this node.
+        @definition = nil
+        self.define_singleton_method(:type) do
           @cached_type
         end
         @cached_type
@@ -28,4 +37,3 @@ module Plumb
     end
   end
 end
-

data/lib/plumb/disjunction.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Plumb
+  # The runtime shared by {Plumb::Or} (left-biased choice) and {Plumb::Union} (the
+  # lattice join) — the dual of {Plumb::Conjunction}. Both try `left` and retry
+  # `right` with the original value on failure, and differ only in how types flow:
+  #
+  #   - a CHOICE may have CONVERTING branches, so its ends genuinely differ:
+  #     `Integer | String.transform(:to_i)` accepts a String but produces an Integer.
+  #   - a UNION is a type — every branch returns its value untouched — so it is its
+  #     own output type, needing no #value_preserving? recursion and no rebuild.
+  module Disjunction
+    # @param left [Composable]
+    # @param right [Composable]
+    # @return [Union, Or]
+    def self.build(left, right)
+      if Plumb::Subtyping.value_preserving?(left) && Plumb::Subtyping.value_preserving?(right)
+        Union.new(left, right)
+      else
+        Or.new(left, right)
+      end
+    end
+
+    attr_reader :children
+
+    # Identical for both nodes, which differ only in how types flow.
+    def initialize(left, right)
+      @left = Composable.wrap(left)
+      @right = Composable.wrap(right)
+      @children = [@left, @right].freeze
+      freeze
+    end
+
+    # (A | B).input_type == A.input_type | B.input_type — shared by both nodes.
+    #
+    # A Union cannot shortcut this to `self` the way it can #output_type, because a
+    # branch may ACCEPT more than it describes: a bare-matcher Constraint reports
+    # `input_type` Any, so a factored `String[/d/] | String[/c/]` consumes Any, and a
+    # Union claiming to consume only itself would fail `String >> that`.
+    #
+    # Rebuilt through .build, not the receiver's class: a disjunction may be a
+    # computation, but its projections are types, so
+    # `(String->Integer | Integer->String).input_type` is a Union and compares equal
+    # to a hand-written `String | Integer`.
+    #
+    # Lazy, or #initialize would recurse building its own io types. Returns self when
+    # both children are their own input type, so Subtyping.resolved_input converges on
+    # identity without allocating.
+    def input_type
+      l = @left.input_type
+      r = @right.input_type
+      l.equal?(@left) && r.equal?(@right) ? self : Disjunction.build(l, r)
+    end
+
+    # Rebuild around new branches, RECLASSIFYING by what they are.
+    # @see Conjunction#with_children for why this must not preserve the class.
+    def with_children(children) = Disjunction.build(children[0], children[1])
+
+    private def _inspect
+      %((#{@left.inspect} | #{@right.inspect}))
+    end
+
+    def call(result)
+      # Snapshot the input value: @left may flip the cursor to invalid in place,
+      # so we need the original to retry @right on the same object.
+      original = result.value
+
+      left_result = @left.call(result)
+      return left_result if left_result.valid?
+
+      # Capture left's errors before reusing the cursor — if @left mutated
+      # `result` in place, `left_result` IS `result` and the reset below would
+      # wipe them.
+      left_raw = left_result.errors
+
+      right_result = @right.call(result.reset(original))
+      return right_result if right_result.valid?
+
+      # Both branches failed. Combine the two error sets, then reuse right's
+      # already-invalid cursor in place rather than allocating another — a union can
+      # be expensive in composite ORed types. `right_result.errors` is read BEFORE
+      # #invalid! overwrites it.
+      merged = Disjunction.merge_errors(left_raw, right_result.errors)
+      right_result.invalid!(errors: merged)
+    end
+
+    # Combining the errors of failed ALTERNATIVES is a monoid: `nil` is the identity,
+    # concatenation the operation. ASSOCIATIVITY is the law that matters — `(A|B)|C`
+    # and `A|(B|C)` are the same set of alternatives and owe the same errors, so
+    # taking only `errors.first` from the right (as this once did) drops every
+    # alternative after the first in a right-nested union.
+    #
+    # Non-destructive: never appends to the left result's own array, which has already
+    # been handed out as an #errors value. Costs one extra Array, and only for three or
+    # more alternatives.
+    #
+    # ONLY for alternatives — a record's or array's errors are a Hash keyed by
+    # field/index, which is meaningful structure this is never applied to.
+    #
+    # @param left [Object, nil] the left alternative's errors
+    # @param right [Object, nil] the right alternative's errors
+    # @return [Object, nil]
+    def self.merge_errors(left, right)
+      return right if left.nil?
+      return left if right.nil?
+
+      merged = left.is_a?(::Array) ? left.dup : [left]
+      right.is_a?(::Array) ? merged.concat(right) : merged.push(right)
+      merged
+    end
+  end
+end