plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/metadata_visitor.rb

@@ -3,6 +3,10 @@
 require 'plumb/visitor_handlers'
 
 module Plumb
+  # Collects user-provided metadata for a type (via #metadata, custom step
+  # metadata, and policy arguments). Any type-bound information (the expected
+  # Ruby types, patterns, ranges, static values, etc.) is intentionally NOT
+  # collected here — it is described by #input_type / #output_type instead.
   class MetadataVisitor
     include VisitorHandlers
 
@@ -11,8 +15,6 @@ module Plumb
     end
 
     def on_missing_handler(node, props, _method_name)
-      return props.merge(type: node) if node.instance_of?(Class)
-
       return props unless node.respond_to?(:children)
 
       node.children.reduce(props) do |acc, child|
@@ -20,44 +22,44 @@ module Plumb
       end
     end
 
-    on(:step) do |node, props|
-      props.merge(node._metadata)
-    end
-
-    on(::Regexp) do |node, props|
-      props.merge(pattern: node, type: props[:type] || String)
+    on(:hash) do |_node, props|
+      props
     end
 
-    on(::Range) do |node, props|
-      type = props[:type] || (node.begin || node.end).class
-      props.merge(match: node, type:)
+    on(:never) do |_node, props|
+      props
     end
 
-    on(:hash) do |_node, props|
-      props.merge(type: Hash)
+    # A refinement matcher carries its base; any user metadata lives on the base
+    # (the matcher itself is type-bound info we don't collect), so follow it.
+    on(:constraint) do |node, props|
+      node.base ? visit(node.base, props) : props
     end
 
+    # This visitor doesn't reason about types, so the Conjunction/Disjunction split
+    # makes no difference to it: :intersection and :union reach these same handlers
+    # through VisitorHandlers::NODE_NAME_FALLBACKS. Registering duplicate bodies
+    # would be a second mechanism for one job, and the copies could drift.
     on(:and) do |node, props|
       left, right = node.children.map { |child| visit(child) }
-      type = right[:type] || left[:type]
-      props = props.merge(left).merge(right)
-      props = props.merge(type:) if type
-      props
+      props.merge(left).merge(right)
     end
 
-    on(:or) do |node, props|
-      child_metas = node.children.map { |child| visit(child) }
-      types = child_metas.map { |child| child[:type] }.flatten.compact
-      types = types.first if types.size == 1
-      child_metas.reduce(props) do |acc, child|
-        acc.merge(child)
-      end.merge(type: types)
+    # A factored union is transparent for metadata — its wrapped And carries the
+    # base + disjunction, so delegate to it.
+    on(:refined_union) do |node, props|
+      visit(node.type, props)
     end
 
-    on(:static) do |node, props|
-      value = node.children[0]
-      type = value.is_a?(Class) ? value : value.class
-      props.merge(static: value, type:)
+    on(:function) do |node, props|
+      left, right = node.children.map { |child| visit(child) }
+      props.merge(left).merge(right)
+    end
+
+    on(:or) do |node, props|
+      node.children
+          .map { |child| visit(child) }
+          .reduce(props) { |acc, child| acc.merge(child) }
     end
 
     on(:policy) do |node, props|
@@ -67,7 +69,7 @@ module Plumb
     end
 
     on(:boolean) do |_node, props|
-      props.merge(type: 'boolean')
+      props
     end
 
     on(:metadata) do |node, props|
@@ -76,23 +78,23 @@ module Plumb
     end
 
     on(:hash_map) do |_node, props|
-      props.merge(type: Hash)
+      props
     end
 
     on(:array) do |_node, props|
-      props.merge(type: Array)
+      props
     end
 
     on(:stream) do |_node, props|
-      props.merge(type: Enumerator)
+      props
     end
 
     on(:tuple) do |_node, props|
-      props.merge(type: Array)
+      props
     end
 
     on(:tagged_hash) do |_node, props|
-      props.merge(type: Hash)
+      props
     end
 
     on(Proc) do |_node, props|

data/lib/plumb/never_class.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'plumb/composable'
+
+module Plumb
+  # The bottom type — the dual of AnyClass. No value inhabits it, so it always
+  # invalidates. It is produced by a provably-empty intersection (see
+  # Composable#& / Subtyping.intersect) and reduces at composition time:
+  #   A & Never == Never   (Never dominates the meet)
+  #   A | Never == A       (Never is absorbed by the join)
+  #   Never >> A == Never
+  # As a subtype, Never is below everything: `Never <= X` for all X (its
+  # #subtype_of? hook always says yes), and nothing but Never is <= Never.
+  class NeverClass
+    include Composable
+
+    # Never dominates intersection and short-circuits sequencing/narrowing.
+    def &(_other) = self
+    def >>(_other) = self
+    def /(_other) = self
+
+    # Never is the identity of union: `Never | X == X`. Route through the hook
+    # (not bare Composable.wrap) so a context-resolving operand — an Encoder
+    # orients, a Codec raises at composition — is handled like every other #|
+    # rather than leaking in as an unresolved node.
+    def |(other) = Composable.resolve_operand(other, op: :|, left: self)
+
+    def call(result) = result.invalid!(errors: 'no value is allowed (Never)')
+
+    # Bottom is a subtype of every type. The mirror direction (`X <= Never`) is
+    # left to the default leaf hook, which is true only reflexively (X == Never).
+    def subtype_of?(_other) = true
+
+    # It never succeeds, so it never changes a value — value-preserving like Any,
+    # which keeps union absorption uniform.
+    def value_preserving? = true
+  end
+end

data/lib/plumb/node_mapper.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Plumb
+  # THE STRUCTURAL REWRITE PRIMITIVE: map a node's Composable sub-types through a
+  # block and rebuild the node around the results — or return the ORIGINAL node
+  # when no sub-type changed.
+  #
+  # The identity guard is why this belongs in one place: every rewriting pass depends
+  # on an untouched subtree coming back `equal?` — so a caller can tell "nothing
+  # happened" from "rebuilt identically", and a no-op pass allocates nothing — and it
+  # must hold uniformly across a dozen node shapes. {Plumb::Decorator} is the
+  # cautionary tale: it grew its own `case` over five node types and silently recursed
+  # into no container or wrapper, so a block never saw a schema's fields.
+  #
+  # Each node contributes only its own rebuild, via the one-line #with_children hook
+  # where its #children already ARE its sub-types. Nodes whose sub-types live
+  # elsewhere — a Metadata's #type, a record's keyed fields — are handled below.
+  #
+  # NOT EXHAUSTIVE, deliberately for now: `map` dispatches on a closed class list, so
+  # a composite it does not name (`Plumb::Implementation`, or a user-defined one) is
+  # returned untouched. Generalizing means a `#map_subtypes(&blk)` hook on each node —
+  # the four branches below are the cases a plain `#with_children(array)` cannot
+  # express. Worth doing when a third pass needs it.
+  #
+  # DELIBERATELY NOT MAPPED, both matching what every existing pass already does:
+  #
+  #   - Constraint's #base. A Constraint carries an error message and a label that
+  #     it does not expose, so rebuilding one would silently drop a custom
+  #     `#check('must start with a')` message.
+  #   - Deferred. Forcing it to recurse would loop forever on a self-referential
+  #     type. A pass that wants to rewrite through one must tie the knot itself
+  #     with its own memo, as Codec::Rewriter does.
+  #
+  # @example
+  #   NodeMapper.map(type) { |child| rewrite(child) }
+  module NodeMapper
+    module_function
+
+    # @param type [Composable]
+    # @yieldparam child [Composable] a Composable sub-type of `type`
+    # @return [Composable] `type` itself when nothing changed, else a rebuilt node
+    def map(type, &blk)
+      # Leaf fast path: a Constraint is the most numerous node in any real graph and
+      # is deliberately not mapped (see above), so answer it before the class tests.
+      return type if type.is_a?(Constraint) || !type.respond_to?(:children)
+
+      case type
+      # Nodes whose #children ARE their sub-types: each contributes its own
+      # #with_children rebuild and this owns the traversal + identity guard.
+      when Conjunction, Disjunction, Function, TupleClass, ArrayClass, HashMap, StreamClass,
+           Not, Policy, TaggedHash
+        map_children(type, &blk)
+      # Transparent wrappers: the sub-type is #type, not a child.
+      when Metadata
+        rewrap(type, type.type, blk) { |t| Metadata.new(t, type.metadata) }
+      when Composable::Node
+        rewrap(type, type.type, blk) { |t| t.as_node(type.node_name, type.args) }
+      # A record's sub-types are its keyed fields.
+      when HashClass
+        map_record(type, &blk)
+      else
+        type
+      end
+    end
+
+    # Map `type`'s #children and rebuild via #with_children, preserving identity
+    # when every child came back the same.
+    def map_children(type, &blk)
+      children = type.children
+      return type if children.empty?
+
+      mapped = children.map(&blk)
+      return type if mapped.each_with_index.all? { |m, i| m.equal?(children[i]) }
+
+      type.with_children(mapped)
+    end
+
+    # Yields (field, key) — the key so a caller can label the position (see
+    # Codec::Rewriter#visit_hash, which builds an error path from it).
+    def map_record(type, &blk)
+      changed = false
+      schema = type._schema.each_with_object({}) do |(key, field), acc|
+        mapped = blk.call(field, key)
+        changed ||= !mapped.equal?(field)
+        acc[key] = mapped
+      end
+      changed ? type.class.new(schema:) : type
+    end
+
+    # A transparent wrapper: map the wrapped type, keep the wrapper when it did not
+    # change, else re-wrap via the block.
+    def rewrap(original, inner, blk)
+      mapped = blk.call(inner)
+      mapped.equal?(inner) ? original : yield(mapped)
+    end
+  end
+end

data/lib/plumb/not.rb

@@ -8,10 +8,27 @@ module Plumb
 
     attr_reader :children, :errors
 
+    # Double negation cancels: `Not(Not(X))` is just `X` — it accepts exactly
+    # what `X` does. So wrapping an existing Not returns the inner type instead
+    # of nesting (covering both `#not` and `Not[]`). A custom error message
+    # keeps the Not, since collapsing would discard it.
+    def self.new(step = nil, errors: nil)
+      wrapped = Composable.wrap(step)
+      return wrapped.children.first if errors.nil? && wrapped.is_a?(self)
+
+      super
+    end
+
+    # @see Plumb::NodeMapper
+    def with_children(children) = self.class.new(children.first, errors: errors)
+
     def initialize(step = nil, errors: nil)
       @step = Composable.wrap(step)
       @errors = errors || "must not be #{step.inspect}"
-      @children = [step].freeze
+      # Store the *wrapped* step (as every container does), so `Not[String]` and
+      # `Not[Types::String]` are the same node — and so the subtype engine isn't
+      # fooled into treating a raw-class child as an atomic leaf.
+      @children = [@step].freeze
       freeze
     end
 
@@ -21,13 +38,28 @@ module Plumb
       self.class.new(step)
     end
 
+    # Negation is contravariant: Not(A) <= Not(B) when B <= A, because excluding
+    # a wider set produces a narrower complement.
+    # @param other [Composable]
+    # @return [Boolean]
+    def subtype_of?(other)
+      return true if self == other
+      return Plumb::Subtyping.subtype?(other.children.first, @step) if other.is_a?(Not)
+
+      super
+    end
+
+    # @return [Boolean] true because negation only changes validity
+    def value_preserving? = true
+
     private def _inspect
       %(Not(#{@step.inspect}))
     end
 
     def call(result)
       result = @step.call(result)
-      result.valid? ? result.invalid(errors: @errors) : result.valid
+      # In-place inversion — no fork here, the cursor is ours to flip.
+      result.valid? ? result.invalid!(errors: @errors) : result.valid!
     end
   end
 end