kumi 0.0.7 → 0.0.8

data/lib/kumi/core/ruby_parser/schema_builder.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module RubyParser
+      class SchemaBuilder
+        include GuardRails
+        include Syntax
+        include ErrorReporting
+
+        DSL_METHODS = %i[value trait input ref literal fn].freeze
+
+        def initialize(context)
+          @context = context
+        end
+
+        def value(name = nil, expr = nil, &blk)
+          update_location
+          validate_value_args(name, expr, blk)
+
+          expression = blk ? build_cascade(&blk) : ensure_syntax(expr)
+          @context.attributes << Kumi::Syntax::ValueDeclaration.new(name, expression, loc: @context.current_location)
+        end
+
+        def trait(*args, **kwargs)
+          update_location
+          raise_syntax_error("keyword trait syntax not supported", location: @context.current_location) unless kwargs.empty?
+          build_positional_trait(args)
+        end
+
+        def input(&blk)
+          return InputProxy.new(@context) unless block_given?
+
+          raise_syntax_error("input block already defined", location: @context.current_location) if @context.input_block_defined?
+          @context.mark_input_block_defined!
+
+          update_location
+          input_builder = InputBuilder.new(@context)
+          input_builder.instance_eval(&blk)
+        end
+
+        def ref(name)
+          update_location
+          Kumi::Syntax::DeclarationReference.new(name, loc: @context.current_location)
+        end
+
+        def literal(value)
+          update_location
+          Kumi::Syntax::Literal.new(value, loc: @context.current_location)
+        end
+
+        def fn(fn_name, *args)
+          update_location
+          expr_args = args.map { |a| ensure_syntax(a) }
+          Kumi::Syntax::CallExpression.new(fn_name, expr_args, loc: @context.current_location)
+        end
+
+        def method_missing(method_name, *args, &block)
+          if args.empty? && !block_given?
+            update_location
+            # Create proxy for declaration references (traits/values)
+            DeclarationReferenceProxy.new(method_name, @context)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(_method_name, _include_private = false)
+          true
+        end
+
+        private
+
+        def update_location
+          # Use caller_locations(2, 1) to skip the DSL method and get the actual user code location
+          # Stack: [0] update_location, [1] DSL method (value/trait/etc), [2] user's DSL code
+          caller_location = caller_locations(2, 1).first
+
+          @context.current_location = Location.new(
+            file: caller_location.path,
+            line: caller_location.lineno,
+            column: 0
+          )
+        end
+
+        def validate_value_args(name, expr, blk)
+          raise_syntax_error("value requires a name as first argument", location: @context.current_location) if name.nil?
+          unless name.is_a?(Symbol)
+            raise_syntax_error("The name for 'value' must be a Symbol, got #{name.class}",
+                               location: @context.current_location)
+          end
+
+          has_expr = !expr.nil?
+          has_block = blk
+
+          if has_expr && has_block
+            raise_syntax_error("value '#{name}' cannot be called with both an expression and a block", location: @context.current_location)
+          elsif !has_expr && !has_block
+            raise_syntax_error("value '#{name}' requires an expression or a block", location: @context.current_location)
+          end
+        end
+
+        def build_positional_trait(args)
+          case args.size
+          when 0
+            raise_syntax_error("trait requires a name and expression", location: @context.current_location)
+          when 1
+            name = args.first
+            raise_syntax_error("trait '#{name}' requires an expression", location: @context.current_location)
+          when 2
+            name, expression = args
+            validate_trait_name(name)
+            expr = ensure_syntax(expression)
+            @context.traits << Kumi::Syntax::TraitDeclaration.new(name, expr, loc: @context.current_location)
+          else
+            handle_deprecated_trait_syntax(args)
+          end
+        end
+
+        def handle_deprecated_trait_syntax(args)
+          if args.size == 3
+            name, = args
+            raise_syntax_error("trait '#{name}' requires exactly 3 arguments: lhs, operator, and rhs", location: @context.current_location)
+          end
+
+          # warn "DEPRECATION: trait(:name, lhs, operator, rhs) syntax is deprecated. Use: trait :name, (lhs operator rhs)"
+
+          if args.size == 4
+            name, lhs, operator, rhs = args
+            build_deprecated_trait(name, lhs, operator, [rhs])
+          else
+            name, lhs, operator, *rhs = args
+            build_deprecated_trait(name, lhs, operator, rhs)
+          end
+        end
+
+        def build_deprecated_trait(name, lhs, operator, rhs)
+          validate_trait_name(name)
+          validate_operator(operator)
+
+          rhs_exprs = rhs.map { |r| ensure_syntax(r) }
+          expr = Kumi::Syntax::CallExpression.new(operator, [ensure_syntax(lhs)] + rhs_exprs, loc: @context.current_location)
+          @context.traits << Kumi::Syntax::TraitDeclaration.new(name, expr, loc: @context.current_location)
+        end
+
+        def validate_trait_name(name)
+          return if name.is_a?(Symbol)
+
+          raise_syntax_error("The name for 'trait' must be a Symbol, got #{name.class}", location: @context.current_location)
+        end
+
+        def validate_operator(operator)
+          unless operator.is_a?(Symbol)
+            raise_syntax_error("expects a symbol for an operator, got #{operator.class}", location: @context.current_location)
+          end
+
+          return if Kumi::Registry.operator?(operator)
+
+          raise_syntax_error("unsupported operator `#{operator}`", location: @context.current_location)
+        end
+
+        def build_cascade(&blk)
+          expression_converter = ExpressionConverter.new(@context)
+          cascade_builder = DslCascadeBuilder.new(expression_converter, @context.current_location)
+          cascade_builder.instance_eval(&blk)
+          Kumi::Syntax::CascadeExpression.new(cascade_builder.cases, loc: @context.current_location)
+        end
+
+        def ensure_syntax(obj)
+          ExpressionConverter.new(@context).ensure_syntax(obj)
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/ruby_parser/sugar.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module RubyParser
+      module Sugar
+        include Syntax
+
+        ARITHMETIC_OPS = {
+          :+ => :add, :- => :subtract, :* => :multiply,
+          :/ => :divide, :% => :modulo, :** => :power
+        }.freeze
+
+        COMPARISON_OPS = %i[< <= > >= == !=].freeze
+
+        LITERAL_TYPES = [
+          Integer, String, Symbol, TrueClass, FalseClass, Float, Regexp, NilClass
+        ].freeze
+
+        # Collection methods that can be applied to arrays/syntax nodes
+        COLLECTION_METHODS = %i[
+          sum size length first last sort reverse unique min max empty? flatten
+          map_with_index indices
+        ].freeze
+
+        def self.ensure_literal(obj)
+          return Kumi::Syntax::Literal.new(obj) if LITERAL_TYPES.any? { |type| obj.is_a?(type) }
+          return obj if obj.is_a?(Syntax::Node)
+          return obj.to_ast_node if obj.respond_to?(:to_ast_node)
+
+          Kumi::Syntax::Literal.new(obj)
+        end
+
+        def self.syntax_expression?(obj)
+          obj.is_a?(Syntax::Node) || obj.respond_to?(:to_ast_node)
+        end
+
+        # Create a call expression with consistent error handling
+        def self.create_call_expression(fn_name, args)
+          Kumi::Syntax::CallExpression.new(fn_name, args)
+        end
+
+        module ExpressionRefinement
+          refine Syntax::Node do
+            # Arithmetic operations
+            ARITHMETIC_OPS.each do |op, op_name|
+              define_method(op) do |other|
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(op_name, [self, other_node])
+              end
+            end
+
+            # Comparison operations
+            COMPARISON_OPS.each do |op|
+              define_method(op) do |other|
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(op, [self, other_node])
+              end
+            end
+
+            # Array access
+            def [](index)
+              Sugar.create_call_expression(:at, [self, Sugar.ensure_literal(index)])
+            end
+
+            # Unary minus
+            def -@
+              Sugar.create_call_expression(:subtract, [Sugar.ensure_literal(0), self])
+            end
+
+            # Logical operations
+            def &(other)
+              Sugar.create_call_expression(:and, [self, Sugar.ensure_literal(other)])
+            end
+
+            def |(other)
+              Sugar.create_call_expression(:or, [self, Sugar.ensure_literal(other)])
+            end
+
+            # Collection methods - single argument (self)
+            COLLECTION_METHODS.each do |method_name|
+              next if method_name == :include? # Special case with element argument
+
+              define_method(method_name) do
+                Sugar.create_call_expression(method_name, [self])
+              end
+            end
+
+            # Special case: include? takes an element argument
+            def include?(element)
+              Sugar.create_call_expression(:include?, [self, Sugar.ensure_literal(element)])
+            end
+          end
+        end
+
+        module NumericRefinement
+          [Integer, Float].each do |klass|
+            refine klass do
+              # Arithmetic operations with syntax expressions
+              ARITHMETIC_OPS.each do |op, op_name|
+                define_method(op) do |other|
+                  if Sugar.syntax_expression?(other)
+                    other_node = Sugar.ensure_literal(other)
+                    Sugar.create_call_expression(op_name, [Kumi::Syntax::Literal.new(self), other_node])
+                  else
+                    super(other)
+                  end
+                end
+              end
+
+              # Comparison operations with syntax expressions
+              COMPARISON_OPS.each do |op|
+                define_method(op) do |other|
+                  if Sugar.syntax_expression?(other)
+                    other_node = Sugar.ensure_literal(other)
+                    Sugar.create_call_expression(op, [Kumi::Syntax::Literal.new(self), other_node])
+                  else
+                    super(other)
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        module StringRefinement
+          refine String do
+            def +(other)
+              if Sugar.syntax_expression?(other)
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(:concat, [Kumi::Syntax::Literal.new(self), other_node])
+              else
+                super
+              end
+            end
+
+            %i[== !=].each do |op|
+              define_method(op) do |other|
+                if Sugar.syntax_expression?(other)
+                  other_node = Sugar.ensure_literal(other)
+                  Sugar.create_call_expression(op, [Kumi::Syntax::Literal.new(self), other_node])
+                else
+                  super(other)
+                end
+              end
+            end
+          end
+        end
+
+        module ArrayRefinement
+          refine Array do
+            # Helper method to check if array contains any syntax expressions
+            def any_syntax_expressions?
+              any? { |item| Sugar.syntax_expression?(item) }
+            end
+
+            # Convert array to syntax list expression with all elements as syntax nodes
+            def to_syntax_list
+              syntax_elements = map { |item| Sugar.ensure_literal(item) }
+              Kumi::Syntax::ArrayExpression.new(syntax_elements)
+            end
+
+            # Create array method that works with syntax expressions
+            def self.define_array_syntax_method(method_name, has_argument: false)
+              define_method(method_name) do |*args|
+                if any_syntax_expressions?
+                  array_literal = to_syntax_list
+                  call_args = [array_literal]
+                  call_args.concat(args.map { |arg| Sugar.ensure_literal(arg) }) if has_argument
+                  Sugar.create_call_expression(method_name, call_args)
+                else
+                  super(*args)
+                end
+              end
+            end
+
+            # Define collection methods without arguments
+            %i[sum size length first last sort reverse unique min max empty? flatten].each do |method_name|
+              define_array_syntax_method(method_name)
+            end
+
+            # Define methods with arguments
+            define_array_syntax_method(:include?, has_argument: true)
+          end
+        end
+
+        module ModuleRefinement
+          refine Module do
+            # Allow modules to provide schema utilities and helpers
+            def with_schema_utilities
+              include Kumi::Schema if respond_to?(:include)
+              extend Kumi::Schema if respond_to?(:extend)
+            end
+
+            # Helper for defining schema constants that can be used in multiple schemas
+            def schema_const(name, value)
+              const_set(name, value.freeze)
+            end
+
+            # Enable easy schema composition
+            def compose_schema(*modules)
+              modules.each do |mod|
+                include mod if mod.is_a?(Module)
+              end
+            end
+          end
+        end
+
+        # Shared refinement for proxy objects that need to handle operators
+        # Both DeclarationReferenceProxy and InputFieldProxy can use this
+        module ProxyRefinement
+          def self.extended(proxy_class)
+            # Add operator methods directly to the proxy class
+            proxy_class.class_eval do
+              # Arithmetic operations
+              ARITHMETIC_OPS.each do |op, op_name|
+                define_method(op) do |other|
+                  ast_node = to_ast_node
+                  other_node = Sugar.ensure_literal(other)
+                  Sugar.create_call_expression(op_name, [ast_node, other_node])
+                end
+              end
+
+              # Comparison operations (including == and != that don't work with refinements)
+              COMPARISON_OPS.each do |op|
+                define_method(op) do |other|
+                  ast_node = to_ast_node
+                  other_node = Sugar.ensure_literal(other)
+                  Sugar.create_call_expression(op, [ast_node, other_node])
+                end
+              end
+
+              # Logical operations
+              define_method(:&) do |other|
+                ast_node = to_ast_node
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(:and, [ast_node, other_node])
+              end
+
+              define_method(:|) do |other|
+                ast_node = to_ast_node
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(:or, [ast_node, other_node])
+              end
+
+              # Array access
+              define_method(:[]) do |index|
+                ast_node = to_ast_node
+                Sugar.create_call_expression(:at, [ast_node, Sugar.ensure_literal(index)])
+              end
+
+              # Unary minus
+              define_method(:-@) do
+                ast_node = to_ast_node
+                Sugar.create_call_expression(:subtract, [Sugar.ensure_literal(0), ast_node])
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/ruby_parser.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Ruby DSL parser for Kumi schemas
+    # Converts Ruby block syntax into AST nodes
+    module RubyParser
+      # This module contains all Ruby DSL parsing functionality
+      # The main entry point is through Dsl.build_syntax_tree
+    end
+  end
+end

data/lib/kumi/core/schema_instance.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # A bound pair of <compiled schema + context>.  Immutable.
+    #
+    # Public API ----------------------------------------------------------
+    #   instance.evaluate                # => full Hash of all bindings
+    #   instance.evaluate(:tax_due, :rate)
+    #   instance.slice(:tax_due)         # alias for evaluate(*keys)
+    #   instance.explain(:tax_due)       # pretty trace string
+    #   instance.input                   # original context (read‑only)
+
+    class SchemaInstance
+      attr_reader :compiled_schema, :metadata, :context
+
+      def initialize(compiled_schema, metadata, context)
+        @compiled_schema = compiled_schema # Kumi::Core::CompiledSchema
+        @metadata = metadata # Frozen state hash
+        @context  = context.is_a?(EvaluationWrapper) ? context : EvaluationWrapper.new(context)
+      end
+
+      # Hash‑like read of one or many bindings
+      def evaluate(*key_names)
+        if key_names.empty?
+          @compiled_schema.evaluate(@context)
+        else
+          @compiled_schema.evaluate(@context, *key_names)
+        end
+      end
+
+      def slice(*key_names)
+        return {} if key_names.empty?
+
+        evaluate(*key_names)
+      end
+
+      def [](key_name)
+        evaluate(key_name)[key_name]
+      end
+
+      # Update input values and clear affected cached computations
+      def update(**changes)
+        changes.each do |field, value|
+          # Validate field exists
+          raise ArgumentError, "unknown input field: #{field}" unless input_field_exists?(field)
+
+          # Validate domain constraints
+          validate_domain_constraint(field, value)
+
+          # Update the input data
+          @context[field] = value
+
+          # Clear affected cached values using transitive closure by default
+          if ENV["KUMI_SIMPLE_CACHE"] == "true"
+            # Simple fallback: clear all cached values
+            @context.clear_cache
+          else
+            # Default: selective cache clearing using precomputed transitive closure
+            affected_keys = find_dependent_declarations_optimized(field)
+            affected_keys.each { |key| @context.clear_cache(key) }
+          end
+        end
+
+        self # Return self for chaining
+      end
+
+      private
+
+      def input_field_exists?(field)
+        # Check if field is declared in input block
+        input_meta = @metadata[:inputs] || {}
+        input_meta.key?(field) || @context.key?(field)
+      end
+
+      def validate_domain_constraint(field, value)
+        input_meta = @metadata[:inputs] || {}
+        field_meta = input_meta[field]
+        return unless field_meta&.dig(:domain)
+
+        domain = field_meta[:domain]
+        return unless violates_domain?(value, domain)
+
+        raise ArgumentError, "value #{value} is not in domain #{domain}"
+      end
+
+      def violates_domain?(value, domain)
+        case domain
+        when Range
+          !domain.include?(value)
+        when Array
+          !domain.include?(value)
+        when Proc
+          # For Proc domains, we can't statically analyze
+          false
+        else
+          false
+        end
+      end
+
+      def find_dependent_declarations_optimized(field)
+        # Use precomputed transitive closure for true O(1) lookup!
+        transitive_dependents = @metadata[:dependents]
+        return [] unless transitive_dependents
+
+        # This is truly O(1) - just array lookup, no traversal needed
+        transitive_dependents[field] || []
+      end
+    end
+  end
+end

data/lib/kumi/core/types/builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Types
+      # Builds complex type structures
+      class Builder
+        def self.array(elem_type)
+          raise ArgumentError, "Invalid array element type: #{elem_type}" unless Validator.valid_type?(elem_type)
+
+          { array: elem_type }
+        end
+
+        def self.hash(key_type, val_type)
+          raise ArgumentError, "Invalid hash key type: #{key_type}" unless Validator.valid_type?(key_type)
+          raise ArgumentError, "Invalid hash value type: #{val_type}" unless Validator.valid_type?(val_type)
+
+          { hash: [key_type, val_type] }
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/types/compatibility.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Types
+      # Handles type compatibility and unification
+      class Compatibility
+        # Check if two types are compatible
+        def self.compatible?(type1, type2)
+          # Any type is compatible with anything
+          return true if type1 == :any || type2 == :any
+
+          # Exact match
+          return true if type1 == type2
+
+          # Generic array compatibility: :array is compatible with any structured array
+          return true if (type1 == :array && Validator.array_type?(type2)) ||
+                         (type2 == :array && Validator.array_type?(type1))
+
+          # Numeric compatibility
+          return true if numeric_compatible?(type1, type2)
+
+          # Array compatibility
+          return array_compatible?(type1, type2) if array_types?(type1, type2)
+
+          # Hash compatibility
+          return hash_compatible?(type1, type2) if hash_types?(type1, type2)
+
+          false
+        end
+
+        # Find the most specific common type between two types
+        def self.unify(type1, type2)
+          return type1 if type1 == type2
+
+          # :any unifies to the other type (more specific)
+          return type2 if type1 == :any
+          return type1 if type2 == :any
+
+          # Generic array unification: structured array is more specific than :array
+          return type2 if type1 == :array && Validator.array_type?(type2)
+          return type1 if type2 == :array && Validator.array_type?(type1)
+
+          # Numeric unification
+          if numeric_compatible?(type1, type2)
+            return :integer if type1 == :integer && type2 == :integer
+
+            return :float # One or both are float
+          end
+
+          # Array unification
+          if array_types?(type1, type2)
+            elem1 = type1[:array]
+            elem2 = type2[:array]
+            unified_elem = unify(elem1, elem2)
+            return Kumi::Core::Types.array(unified_elem)
+          end
+
+          # Hash unification
+          if hash_types?(type1, type2)
+            key1, val1 = type1[:hash]
+            key2, val2 = type2[:hash]
+            unified_key = unify(key1, key2)
+            unified_val = unify(val1, val2)
+            return Kumi::Core::Types.hash(unified_key, unified_val)
+          end
+
+          # Fall back to :any for incompatible types
+          :any
+        end
+
+        def self.numeric_compatible?(type1, type2)
+          numeric_types = %i[integer float]
+          numeric_types.include?(type1) && numeric_types.include?(type2)
+        end
+
+        def self.array_types?(type1, type2)
+          Validator.array_type?(type1) && Validator.array_type?(type2)
+        end
+
+        def self.hash_types?(type1, type2)
+          Validator.hash_type?(type1) && Validator.hash_type?(type2)
+        end
+
+        def self.array_compatible?(type1, type2)
+          compatible?(type1[:array], type2[:array])
+        end
+
+        def self.hash_compatible?(type1, type2)
+          compatible?(type1[:hash][0], type2[:hash][0]) &&
+            compatible?(type1[:hash][1], type2[:hash][1])
+        end
+      end
+    end
+  end
+end