rigortype 0.1.5 → 0.1.7

data/lib/rigor/inference/hkt_body_parser.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require_relative "hkt_body"
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # ADR-20 slice 2b — parses the body of an
+    # `HktRegistry::Definition` (a `String`, as populated by
+    # Slice 1's `HktDirectives.parse_define` from
+    # `%a{rigor:v1:hkt_define}` payloads) into the `HktBody`
+    # node tree the Slice 2a reducer evaluates against.
+    #
+    # The minimum-viable grammar covered here is the
+    # union-of-atoms-and-parameterised-forms subset of ADR-20
+    # § D3 — sufficient for `JSON.parse`'s `json::value`
+    # recursive sum and for any other recursive-data-shape
+    # signatures (Lisp value trees, dry-types refinements
+    # without conditionals). The conditional / indexed-access
+    # forms (`E <: T ? A : B`, `E in [k1, k2]`) drafted in D3
+    # remain a follow-up slice — bodies that contain `?`
+    # raise `ParseError` and the calling directive parser
+    # drops the body_tree (the body String remains stored and
+    # the reducer falls back to `app.bound`).
+    #
+    # ## Grammar (slice 2b)
+    #
+    #     body         := union
+    #     union        := type_expr ("|" type_expr)*
+    #     type_expr    := atom | nominal_app | app_ref | param
+    #     atom         := "nil" | "true" | "false" | "bool" | "untyped"
+    #     param        := UCNAME   (when UCNAME ∈ params)
+    #     nominal_app  := class_name ("[" type_expr ("," type_expr)* "]")?
+    #     class_name   := "::"? UCNAME ("::" UCNAME)*
+    #     app_ref      := "App" "[" uri "," type_expr ("," type_expr)* "]"
+    #     uri          := IDENT ("::" IDENT)+
+    #     UCNAME       := /[A-Z]\w*/
+    #     IDENT        := /[a-z_]\w*/
+    #
+    # ## Disambiguation
+    #
+    # The same syntactic UCNAME spells both a parameter
+    # reference (`K` when `params = [:K]`) and a nominal class
+    # name (`Integer`). The parser resolves by checking the
+    # `params` set passed to {.parse}; an unknown UCNAME is
+    # treated as a nominal class name. `App` is reserved at
+    # the head position of an `App[...]` form; using `App` as
+    # a class name is therefore not supported.
+    #
+    # Atoms are kept verbatim as `HktBody::TypeLeaf` nodes
+    # wrapping the appropriate `Rigor::Type::*` carrier:
+    # `nil` / `true` / `false` produce `Constant` carriers;
+    # `bool` produces the `Constant<true> | Constant<false>`
+    # union; `untyped` produces `Combinator.untyped`
+    # (i.e. `Dynamic[Top]`). Nominal class names produce raw
+    # `Type::Nominal` carriers (no `name_scope` resolution at
+    # this slice — the reducer trusts the name verbatim).
+    module HktBodyParser
+      class ParseError < StandardError; end
+
+      module_function
+
+      def parse(string, params:)
+        raise ArgumentError, "string must be a String, got #{string.class}" unless string.is_a?(String)
+        raise ArgumentError, "params must be an Array, got #{params.class}" unless params.is_a?(Array)
+
+        params_set = params.to_h { |p| [p.to_sym, true] }
+        tokens = Tokenizer.new(string).tokenize
+        parser = Parser.new(tokens, params_set)
+        result = parser.parse_union
+        parser.expect_eof!
+        result
+      end
+
+      Token = Data.define(:kind, :value, :pos)
+
+      class Tokenizer
+        SCANNER_REGEX = /
+          \G
+          (?:
+            (?<ws>\s+)
+          | (?<lb>\[)
+          | (?<rb>\])
+          | (?<lparen>\()
+          | (?<rparen>\))
+          | (?<comma>,)
+          | (?<pipe>\|)
+          | (?<sub><:)
+          | (?<eq>==)
+          | (?<sep>::)
+          | (?<colon>:(?!:))
+          | (?<question>\?)
+          | (?<ident>[a-z_][a-zA-Z0-9_]*)
+          | (?<ucname>[A-Z][a-zA-Z0-9_]*)
+          )
+        /x
+
+        def initialize(string)
+          @string = string
+        end
+
+        TOKEN_KINDS = SCANNER_REGEX.named_captures.keys.freeze
+        private_constant :TOKEN_KINDS
+
+        def tokenize
+          tokens = []
+          pos = 0
+          while pos < @string.size
+            match = SCANNER_REGEX.match(@string, pos)
+            raise ParseError, "unexpected character at position #{pos}: #{@string[pos].inspect}" if match.nil?
+
+            kind = TOKEN_KINDS.find { |k| match[k] }
+            raise ParseError, "internal tokenizer error at position #{pos}" if kind.nil?
+
+            value = match[kind.to_sym]
+            raise ParseError, "internal tokenizer error: no match for #{kind}" if value.nil?
+
+            pos += value.size
+            next if kind == "ws"
+
+            tokens << Token.new(kind: kind.to_sym, value: value, pos: pos - value.size)
+          end
+          tokens
+        end
+      end
+
+      class Parser
+        def initialize(tokens, params_set)
+          @tokens = tokens
+          @pos = 0
+          @params_set = params_set
+        end
+
+        def parse_union
+          arms = [parse_type_expr]
+          while peek_kind == :pipe
+            consume
+            arms << parse_type_expr
+          end
+          return arms.first if arms.size == 1
+
+          HktBody::Union.new(arms: arms)
+        end
+
+        def parse_type_expr
+          tok = peek
+          raise ParseError, "unexpected end of input; expected type expression" if tok.nil?
+
+          case tok.kind
+          when :lparen  then parse_conditional
+          when :ident   then parse_lowercase_atom
+          when :ucname  then parse_ucname_form
+          when :sep     then parse_classname_with_leading_sep
+          else
+            raise ParseError, "unexpected token #{tok.kind} (#{tok.value.inspect}) at position #{tok.pos}"
+          end
+        end
+
+        # ADR-20 § D3 conditional parser. Grammar:
+        #
+        #     conditional := "(" test "?" union ":" union ")"
+        #     test        := type_expr ("<:" | "==") type_expr
+        #
+        # Parens delimit a conditional unambiguously — bare
+        # `(type_expr)` grouping is not supported at this slice
+        # (no use case yet). Branches can be unions; test sides
+        # are single arms (wrap in `App[my_union, ...]` if you
+        # need a union there). `in [opt1, opt2]` membership
+        # tests are programmatically supported via
+        # `HktBody::TestMembership` but the parser does not yet
+        # recognise the `in` keyword (no concrete demand yet).
+        def parse_conditional
+          expect!(:lparen)
+          test = parse_test
+          expect!(:question)
+          then_branch = parse_union
+          expect!(:colon)
+          else_branch = parse_union
+          expect!(:rparen)
+          HktBody::Conditional.new(test: test, then_branch: then_branch, else_branch: else_branch)
+        end
+
+        def parse_test
+          left = parse_type_expr
+          op = peek
+          case op&.kind
+          when :sub
+            consume
+            HktBody::TestSubtype.new(left: left, right: parse_type_expr)
+          when :eq
+            consume
+            HktBody::TestEquality.new(left: left, right: parse_type_expr)
+          when :ident
+            parse_in_membership(left, op_token: op)
+          else
+            actual = op.nil? ? "end of input" : "#{op.kind} (#{op.value.inspect})"
+            raise ParseError, "expected `<:`, `==`, or `in` in conditional test, got #{actual}"
+          end
+        end
+
+        # `left in [opt1, opt2, ...]` membership test.
+        # Distinguished from a lowercase atom by the
+        # subsequent `[` — the only place an identifier
+        # `in` is permitted at this position is membership
+        # syntax.
+        def parse_in_membership(left, op_token:)
+          unless op_token.value == "in"
+            raise ParseError,
+                  "expected `<:`, `==`, or `in` in conditional test, got ident (#{op_token.value.inspect})"
+          end
+
+          consume # in
+          expect!(:lb)
+          options = [parse_type_expr]
+          while peek_kind == :comma
+            consume
+            options << parse_type_expr
+          end
+          expect!(:rb)
+          HktBody::TestMembership.new(left: left, options: options)
+        end
+
+        def parse_lowercase_atom
+          tok = consume
+          type = case tok.value
+                 when "nil"     then Type::Constant.new(nil)
+                 when "true"    then Type::Constant.new(true)
+                 when "false"   then Type::Constant.new(false)
+                 when "bool"    then Type::Combinator.union(Type::Constant.new(true), Type::Constant.new(false))
+                 when "untyped" then Type::Combinator.untyped
+                 else raise ParseError, "unknown atom #{tok.value.inspect} at position #{tok.pos}"
+                 end
+          HktBody::TypeLeaf.new(type: type)
+        end
+
+        def parse_ucname_form
+          tok = peek
+          return parse_app_ref if tok.value == "App"
+
+          if @params_set.key?(tok.value.to_sym) && !class_continuation?
+            consume
+            return HktBody::Param.new(name: tok.value.to_sym)
+          end
+
+          parse_nominal_or_param_with_args
+        end
+
+        # Returns true when the current UCName is followed by
+        # `::` (qualified class name continuation) or `[`
+        # (parameterised application). In either case the
+        # token is a nominal, not a param ref — Slice 2b's
+        # `Param` nodes are always single bare identifiers.
+        def class_continuation?
+          next_tok = @tokens[@pos + 1]
+          next_tok && %i[sep lb].include?(next_tok.kind)
+        end
+
+        def parse_nominal_or_param_with_args
+          class_name = parse_class_name
+          if peek_kind == :lb
+            consume
+            args = parse_arg_list
+            expect!(:rb)
+            HktBody::NominalApp.new(class_name: class_name, args: args)
+          else
+            HktBody::TypeLeaf.new(type: Type::Nominal.new(class_name))
+          end
+        end
+
+        def parse_classname_with_leading_sep
+          # The leading "::" form (`::Foo::Bar`). Consume the
+          # separator so the rest threads through parse_class_name.
+          consume
+          tok = peek
+          raise ParseError, "expected class name after `::`" if tok.nil? || tok.kind != :ucname
+
+          parse_nominal_or_param_with_args
+        end
+
+        def parse_class_name
+          parts = [expect!(:ucname).value]
+          while peek_kind == :sep && @tokens[@pos + 1]&.kind == :ucname
+            consume # ::
+            parts << expect!(:ucname).value
+          end
+          parts.join("::")
+        end
+
+        def parse_app_ref
+          tok = consume
+          raise ParseError, "expected `App[...]`, got #{tok.value.inspect}" unless tok.value == "App"
+
+          expect!(:lb)
+          uri = parse_uri
+          expect!(:comma)
+          args = parse_arg_list
+          expect!(:rb)
+          HktBody::AppRef.new(uri: uri, args: args)
+        end
+
+        def parse_uri
+          parts = [expect!(:ident).value]
+          while peek_kind == :sep
+            consume
+            parts << expect!(:ident).value
+          end
+          raise ParseError, "uri must be namespaced (`a::b`), got #{parts.first.inspect}" if parts.size < 2
+
+          parts.join("::").to_sym
+        end
+
+        # Arg list for `Foo[A, B, C]` and `App[uri, A, B]`
+        # forms. Each arg is parsed as a union so per-arg
+        # `A | B` forms work (`Array[K | nil]`); the COMMA
+        # at the top level still separates args, so
+        # `Hash[K, V]` reads as two args (each a single-arm
+        # union that collapses to the arm) rather than one
+        # union of two.
+        def parse_arg_list
+          args = [parse_union]
+          while peek_kind == :comma
+            consume
+            args << parse_union
+          end
+          args
+        end
+
+        def expect_eof!
+          return if @pos >= @tokens.size
+
+          tok = @tokens[@pos]
+          raise ParseError, "expected end of input, got #{tok.kind} (#{tok.value.inspect}) at position #{tok.pos}"
+        end
+
+        private
+
+        def peek
+          @tokens[@pos]
+        end
+
+        def peek_kind
+          @tokens[@pos]&.kind
+        end
+
+        def consume
+          tok = @tokens[@pos]
+          @pos += 1
+          tok
+        end
+
+        def expect!(kind)
+          tok = @tokens[@pos]
+          if tok.nil? || tok.kind != kind
+            actual = tok.nil? ? "end of input" : "#{tok.kind} (#{tok.value.inspect})"
+            raise ParseError, "expected #{kind}, got #{actual}"
+          end
+          @pos += 1
+          tok
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/hkt_reducer.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require_relative "hkt_body"
+
+module Rigor
+  module Inference
+    # ADR-20 Slice 2a — reducer that walks a `Definition`'s
+    # `body_tree` against a concrete `Type::App` and returns a
+    # fully-typed `Rigor::Type`.
+    #
+    # Reduction is the operational interpretation of ADR-20
+    # § D4 ("Evaluation rules"):
+    #
+    # 1. **Resolve `F`.** Look up the registered body via
+    #    `registry.definition(uri)`.
+    # 2. **Substitute arguments.** Walk the body tree, replacing
+    #    `{HktBody::Param}` nodes with the matching positional
+    #    arg from the application.
+    # 3. **Build types.** `{HktBody::TypeLeaf}` returns its
+    #    wrapped type as-is; `{HktBody::Union}` and
+    #    `{HktBody::NominalApp}` route their reduced children
+    #    through `Type::Combinator.union` / `.nominal_of` so
+    #    normalization applies.
+    # 4. **Recurse on `{HktBody::AppRef}` nodes.** Reduce the
+    #    args first; if the resulting `(uri, args)` matches an
+    #    App already on the current reduction stack, return the
+    #    in-progress `Type::App` carrier as-is (lazy
+    #    self-reference handling — the standard "tying the
+    #    knot" trick for recursive type aliases like
+    #    `json::value`). Otherwise build a fresh
+    #    `Type::App` and recursively reduce it against the
+    #    same registry, sharing the fuel budget.
+    # 5. **Fuel budget.** Each visited node consumes one unit.
+    #    On exhaustion, reduction unwinds to `app.bound`.
+    #
+    # The reducer is **pure** with respect to its inputs (the
+    # registry + the App) but uses a per-call mutable state
+    # bag for fuel + cycle tracking. Concurrent reductions
+    # MUST allocate fresh reducers (or fresh `_reduce` calls)
+    # — the per-call state is not shared.
+    class HktReducer
+      DEFAULT_FUEL = 64
+
+      class FuelExhausted < StandardError; end
+
+      def initialize(registry)
+        raise ArgumentError, "registry must be an HktRegistry" unless registry.is_a?(HktRegistry)
+
+        @registry = registry
+      end
+
+      # Reduce `app` against the registry.
+      #
+      # @param app [Rigor::Type::App]
+      # @param fuel [Integer] reduction-step budget (default 64
+      #   per ADR-20 WD3). Each visited body node costs one
+      #   unit. On exhaustion the reduction returns `app.bound`.
+      # @return [Rigor::Type] the reduced type, or `app.bound`
+      #   when reduction is impossible (URI not defined, arity
+      #   mismatch, body_tree absent, fuel exhausted).
+      def reduce(app, fuel: DEFAULT_FUEL)
+        raise ArgumentError, "expected a Rigor::Type::App, got #{app.class}" unless app.is_a?(Type::App)
+
+        definition = @registry.definition(app.uri)
+        return app.bound if definition.nil? || definition.body_tree.nil?
+        return app.bound if definition.params.size != app.args.size
+
+        state = State.new(fuel: fuel)
+        begin
+          state.with_in_progress(app.uri, app.args, app) do
+            walk(definition.body_tree, bindings: bindings_for(definition, app.args), state: state) || app.bound
+          end
+        rescue FuelExhausted
+          app.bound
+        end
+      end
+
+      private
+
+      def bindings_for(definition, args)
+        definition.params.zip(args).to_h
+      end
+
+      def walk(node, bindings:, state:)
+        state.consume_fuel!
+
+        case node
+        when HktBody::TypeLeaf
+          node.type
+        when HktBody::Param
+          bindings.fetch(node.name) do
+            raise ArgumentError, "unknown param #{node.name.inspect}; declared: #{bindings.keys}"
+          end
+        when HktBody::Union
+          reduced = node.arms.map { |arm| walk(arm, bindings: bindings, state: state) }
+          Type::Combinator.union(*reduced)
+        when HktBody::NominalApp
+          reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
+          Type::Combinator.nominal_of(node.class_name, type_args: reduced_args)
+        when HktBody::AppRef
+          reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
+          reduce_app_ref(node.uri, reduced_args, state: state)
+        when HktBody::Conditional
+          walk_conditional(node, bindings: bindings, state: state)
+        else
+          raise ArgumentError, "unknown body node: #{node.class}"
+        end
+      end
+
+      # ADR-20 § D3 conditional reduction. Resolves the test
+      # against the current bindings and picks a branch:
+      #
+      # - test = `yes` → return the reduced `then_branch`.
+      # - test = `no`  → return the reduced `else_branch`.
+      # - test = `maybe` → widen to the union of both
+      #   reduced branches (per ADR-20 WD7).
+      def walk_conditional(node, bindings:, state:)
+        verdict = evaluate_test(node.test, bindings: bindings, state: state)
+        case verdict
+        when :yes
+          walk(node.then_branch, bindings: bindings, state: state)
+        when :no
+          walk(node.else_branch, bindings: bindings, state: state)
+        else
+          # `:maybe` — widen to the union of both branches.
+          then_t = walk(node.then_branch, bindings: bindings, state: state)
+          else_t = walk(node.else_branch, bindings: bindings, state: state)
+          Type::Combinator.union(then_t, else_t)
+        end
+      end
+
+      def evaluate_test(test, bindings:, state:)
+        case test
+        when HktBody::TestSubtype
+          left = walk(test.left, bindings: bindings, state: state)
+          right = walk(test.right, bindings: bindings, state: state)
+          subtype_verdict(left, right)
+        when HktBody::TestEquality
+          left = walk(test.left, bindings: bindings, state: state)
+          right = walk(test.right, bindings: bindings, state: state)
+          equality_verdict(left, right)
+        when HktBody::TestMembership
+          left = walk(test.left, bindings: bindings, state: state)
+          options = test.options.map { |o| walk(o, bindings: bindings, state: state) }
+          membership_verdict(left, options)
+        else
+          raise ArgumentError, "unknown test node: #{test.class}"
+        end
+      end
+
+      # `left <: right`. Slice 7a verdict policy: structural
+      # equality is `:yes`; clearly-disjoint nominal /
+      # constant pairs are `:no`; everything else is `:maybe`
+      # (widens to the union per ADR-20 WD7 — robustness
+      # principle keeps us conservative on undecided tests).
+      def subtype_verdict(left, right)
+        return :yes if left == right
+
+        # Both Nominals with different class names AND
+        # neither carries Dynamic — `:no` (statically
+        # disjoint). For any other shape pair, `:maybe`.
+        return :no if disjoint_nominals?(left, right)
+        return :no if disjoint_constants?(left, right)
+
+        :maybe
+      end
+
+      # Structural equality verdict — same shape as
+      # subtype_verdict but symmetric.
+      def equality_verdict(left, right)
+        return :yes if left == right
+        return :no if disjoint_nominals?(left, right)
+        return :no if disjoint_constants?(left, right)
+
+        :maybe
+      end
+
+      def membership_verdict(left, options)
+        verdicts = options.map { |o| equality_verdict(left, o) }
+        return :yes if verdicts.include?(:yes)
+        return :no if verdicts.all? { |v| v == :no }
+
+        :maybe
+      end
+
+      def disjoint_nominals?(left, right)
+        return false unless left.is_a?(Type::Nominal) && right.is_a?(Type::Nominal)
+
+        left.class_name != right.class_name
+      end
+
+      def disjoint_constants?(left, right)
+        return false unless left.is_a?(Type::Constant) && right.is_a?(Type::Constant)
+
+        left.value != right.value
+      end
+
+      def reduce_app_ref(uri, reduced_args, state:)
+        # Cycle detection — when the same `(uri, args)` is
+        # already on the reduction stack, return the
+        # in-progress App carrier as-is so recursive type
+        # aliases (`Array[App[json::value, K]]` inside the
+        # `json::value` body) terminate.
+        existing = state.in_progress_for(uri, reduced_args)
+        return existing if existing
+
+        registration = @registry.registration(uri)
+        bound = registration&.bound || Type::Combinator.untyped
+        new_app = Type::App.new(uri, reduced_args, bound: bound)
+
+        definition = @registry.definition(uri)
+        return new_app if definition.nil? || definition.body_tree.nil?
+        return new_app if definition.params.size != reduced_args.size
+
+        state.with_in_progress(uri, reduced_args, new_app) do
+          walk(definition.body_tree, bindings: bindings_for(definition, reduced_args), state: state) || new_app
+        end
+      end
+
+      # Per-call mutable bag carrying the remaining fuel
+      # budget and the active reduction stack (for cycle
+      # detection). Not shared across `reduce` calls.
+      class State
+        def initialize(fuel:)
+          @fuel = fuel
+          @in_progress = {}
+        end
+
+        def consume_fuel!
+          raise FuelExhausted if @fuel <= 0
+
+          @fuel -= 1
+        end
+
+        def in_progress_for(uri, args)
+          @in_progress[[uri, args]]
+        end
+
+        def with_in_progress(uri, args, app)
+          key = [uri, args]
+          previous = @in_progress[key]
+          @in_progress[key] = app
+          begin
+            yield
+          ensure
+            if previous.nil?
+              @in_progress.delete(key)
+            else
+              @in_progress[key] = previous
+            end
+          end
+        end
+      end
+    end
+  end
+end