kumi 0.0.4 → 0.0.5

data/lib/kumi/evaluation_wrapper.rb

@@ -3,20 +3,36 @@
 module Kumi
   EvaluationWrapper = Struct.new(:ctx) do
     def initialize(ctx)
-      @ctx = ctx
+      super
       @__schema_cache__ = {} # memoization cache for bindings
     end
 
     def [](key)
-      @ctx[key]
+      ctx[key]
+    end
+
+    def []=(key, value)
+      ctx[key] = value
     end
 
     def keys
-      @ctx.keys
+      ctx.keys
     end
 
     def key?(key)
-      @ctx.key?(key)
+      ctx.key?(key)
+    end
+
+    def clear
+      @__schema_cache__.clear
+    end
+
+    def clear_cache(*keys)
+      if keys.empty?
+        @__schema_cache__.clear
+      else
+        keys.each { |key| @__schema_cache__.delete(key) }
+      end
     end
   end
 end

data/lib/kumi/explain.rb

@@ -56,16 +56,16 @@ module Kumi
 
       def format_call_expression(expr, indent_context: 0, nested: false)
         if pretty_printable?(expr.fn_name)
-          format_pretty_function(expr, expr.fn_name, indent_context, nested)
+          format_pretty_function(expr, expr.fn_name, indent_context, nested: nested)
         else
           format_generic_function(expr, indent_context)
         end
       end
 
-      def format_pretty_function(expr, fn_name, _indent_context, nested = false)
+      def format_pretty_function(expr, fn_name, _indent_context, nested: false)
         if needs_evaluation?(expr.args) && !nested
           # For top-level expressions, show the flattened symbolic form and evaluation
-          if is_chain_of_same_operator?(expr, fn_name)
+          if chain_of_same_operator?(expr, fn_name)
             # For chains like a + b + c, flatten to show all operands
             all_operands = flatten_operator_chain(expr, fn_name)
             symbolic_operands = all_operands.map { |op| format_expression(op, indent_context: 0, nested: true) }
@@ -88,7 +88,7 @@ module Kumi
           else
             # Regular pretty formatting for non-chain expressions
             symbolic_args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
-            symbolic_format = get_display_format(fn_name, symbolic_args)
+            symbolic_format = display_format(fn_name, symbolic_args)
 
             evaluated_args = expr.args.map do |arg|
               if arg.is_a?(Syntax::TerminalExpressions::Literal)
@@ -103,18 +103,18 @@ module Kumi
                 end
               end
             end
-            evaluated_format = get_display_format(fn_name, evaluated_args)
+            evaluated_format = display_format(fn_name, evaluated_args)
 
           end
           "#{symbolic_format} = #{evaluated_format}"
         else
           # For nested expressions, just show the symbolic form without evaluation details
           args = expr.args.map { |arg| format_expression(arg, indent_context: 0, nested: true) }
-          get_display_format(fn_name, args)
+          display_format(fn_name, args)
         end
       end
 
-      def is_chain_of_same_operator?(expr, fn_name)
+      def chain_of_same_operator?(expr, fn_name)
         return false unless %i[add subtract multiply divide].include?(fn_name)
 
         # Check if any argument is the same operator
@@ -152,7 +152,7 @@ module Kumi
         %i[add subtract multiply divide == != > < >= <= and or not].include?(fn_name)
       end
 
-      def get_display_format(fn_name, args)
+      def display_format(fn_name, args)
         case fn_name
         when :add then args.join(" + ")
         when :subtract then args.join(" - ")

data/lib/kumi/function_registry/collection_functions.rb

@@ -84,6 +84,109 @@ module Kumi
             param_types: [Kumi::Types.array(:any)],
             return_type: Kumi::Types.array(:any),
             description: "Remove duplicate elements from collection"
+          ),
+
+          # Array transformation functions
+          flatten: FunctionBuilder::Entry.new(
+            fn: lambda(&:flatten),
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Flatten nested arrays into a single array"
+          ),
+
+          # Mathematical transformation functions
+          map_multiply: FunctionBuilder::Entry.new(
+            fn: ->(collection, factor) { collection.map { |x| x * factor } },
+            arity: 2,
+            param_types: [Kumi::Types.array(:float), :float],
+            return_type: Kumi::Types.array(:float),
+            description: "Multiply each element by factor"
+          ),
+
+          map_add: FunctionBuilder::Entry.new(
+            fn: ->(collection, value) { collection.map { |x| x + value } },
+            arity: 2,
+            param_types: [Kumi::Types.array(:float), :float],
+            return_type: Kumi::Types.array(:float),
+            description: "Add value to each element"
+          ),
+
+          # Conditional transformation functions
+          map_conditional: FunctionBuilder::Entry.new(
+            fn: lambda { |collection, condition_value, true_value, false_value|
+              collection.map { |x| x == condition_value ? true_value : false_value }
+            },
+            arity: 4,
+            param_types: %i[array any any any],
+            return_type: :array,
+            description: "Transform elements based on condition: if element == condition_value then true_value else false_value"
+          ),
+
+          # Range/index functions for grid operations
+          build_array: FunctionBuilder::Entry.new(
+            fn: lambda { |size, &generator|
+              (0...size).map { |i| generator ? generator.call(i) : i }
+            },
+            arity: 1,
+            param_types: [:integer],
+            return_type: Kumi::Types.array(:any),
+            description: "Build array of given size with index values"
+          ),
+
+          range: FunctionBuilder::Entry.new(
+            fn: ->(start, finish) { (start...finish).to_a },
+            arity: 2,
+            param_types: %i[integer integer],
+            return_type: Kumi::Types.array(:integer),
+            description: "Generate range of integers from start to finish (exclusive)"
+          ),
+
+          # Array slicing and grouping for rendering
+          each_slice: FunctionBuilder::Entry.new(
+            fn: ->(array, size) { array.each_slice(size).to_a },
+            arity: 2,
+            param_types: %i[array integer],
+            return_type: Kumi::Types.array(:array),
+            description: "Group array elements into subarrays of given size"
+          ),
+
+          join: FunctionBuilder::Entry.new(
+            fn: lambda { |array, separator = ""|
+              array.map(&:to_s).join(separator.to_s)
+            },
+            arity: 2,
+            param_types: %i[array string],
+            return_type: :string,
+            description: "Join array elements into string with separator"
+          ),
+
+          # Transform each subarray to string and join the results
+          map_join_rows: FunctionBuilder::Entry.new(
+            fn: lambda { |array_of_arrays, row_separator = "", column_separator = "\n"|
+              array_of_arrays.map { |row| row.join(row_separator.to_s) }.join(column_separator.to_s)
+            },
+            arity: 3,
+            param_types: [Kumi::Types.array(:array), :string, :string],
+            return_type: :string,
+            description: "Join 2D array into string with row and column separators"
+          ),
+
+          # Higher-order collection functions (limited to common patterns)
+          map_with_index: FunctionBuilder::Entry.new(
+            fn: ->(collection) { collection.map.with_index.to_a },
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:any),
+            description: "Map collection elements to [element, index] pairs"
+          ),
+
+          indices: FunctionBuilder::Entry.new(
+            fn: ->(collection) { (0...collection.size).to_a },
+            arity: 1,
+            param_types: [Kumi::Types.array(:any)],
+            return_type: Kumi::Types.array(:integer),
+            description: "Generate array of indices for the collection"
           )
         }
       end

data/lib/kumi/parser/dsl_cascade_builder.rb

@@ -20,7 +20,8 @@ module Kumi
         trait_names = args[0..-2]
         expr = args.last
 
-        condition = create_function_call(:all?, trait_names, on_loc)
+        trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
+        condition = create_fn(:all?, trait_bindings)
         result = ensure_syntax(expr)
         add_case(condition, result)
       end
@@ -32,7 +33,8 @@ module Kumi
         trait_names = args[0..-2]
         expr = args.last
 
-        condition = create_function_call(:any?, trait_names, on_loc)
+        trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
+        condition = create_fn(:any?, trait_bindings)
         result = ensure_syntax(expr)
         add_case(condition, result)
       end
@@ -44,7 +46,8 @@ module Kumi
         trait_names = args[0..-2]
         expr = args.last
 
-        condition = create_function_call(:none?, trait_names, on_loc)
+        trait_bindings = convert_trait_names_to_bindings(trait_names, on_loc)
+        condition = create_fn(:none?, trait_bindings)
         result = ensure_syntax(expr)
         add_case(condition, result)
       end
@@ -80,9 +83,17 @@ module Kumi
         raise_error("cascade '#{method_name}' requires an expression as the last argument", location)
       end
 
-      def create_function_call(function_name, trait_names, location)
-        trait_bindings = trait_names.map { |name| create_binding(name, location) }
-        create_fn(function_name, trait_bindings)
+      def convert_trait_names_to_bindings(trait_names, location)
+        trait_names.map do |name|
+          case name
+          when Symbol
+            create_binding(name, location)
+          when Binding
+            name  # Already a binding from method_missing
+          else
+            raise_error("trait reference must be a symbol or bare identifier, got #{name.class}", location)
+          end
+        end
       end
 
       def add_case(condition, result)

data/lib/kumi/parser/expression_converter.rb

@@ -2,57 +2,125 @@
 
 module Kumi
   module Parser
+    # Converts Ruby objects and DSL expressions into AST nodes
+    # This is the bridge between Ruby's native types and Kumi's syntax tree
     class ExpressionConverter
       include Syntax
       include ErrorReporting
 
+      # Use the same literal types as Sugar module to avoid duplication
+      LITERAL_TYPES = Sugar::LITERAL_TYPES
+
       def initialize(context)
         @context = context
       end
 
+      # Convert any Ruby object into a syntax node
+      # @param obj [Object] The object to convert
+      # @return [Syntax::Node] The corresponding AST node
       def ensure_syntax(obj)
         case obj
-        when Integer, String, TrueClass, FalseClass, Float, Regexp, Symbol
-          Literal.new(obj)
+        when *LITERAL_TYPES
+          create_literal(obj)
         when Array
-          ListExpression.new(obj.map { |e| ensure_syntax(e) })
+          create_list(obj)
         when Syntax::Node
           obj
         else
-          handle_complex_object(obj)
+          handle_custom_object(obj)
         end
       end
 
+      # Create a reference to another declaration
+      # @param name [Symbol] The name to reference
+      # @return [Syntax::Binding] Reference node
       def ref(name)
-        Binding.new(name, loc: @context.current_location)
+        validate_reference_name(name)
+        Binding.new(name, loc: current_location)
       end
 
+      # Create a literal value node
+      # @param value [Object] The literal value
+      # @return [Syntax::Literal] Literal node
       def literal(value)
-        Literal.new(value, loc: @context.current_location)
+        Literal.new(value, loc: current_location)
       end
 
+      # Create a function call expression
+      # @param fn_name [Symbol] The function name
+      # @param args [Array] The function arguments
+      # @return [Syntax::CallExpression] Function call node
       def fn(fn_name, *args)
-        expr_args = args.map { |a| ensure_syntax(a) }
-        CallExpression.new(fn_name, expr_args, loc: @context.current_location)
+        validate_function_name(fn_name)
+        expr_args = convert_arguments(args)
+        CallExpression.new(fn_name, expr_args, loc: current_location)
       end
 
+      # Access the input proxy for field references
+      # @return [InputProxy] Proxy for input field access
       def input
         InputProxy.new(@context)
       end
 
+      # Raise a syntax error with location information
+      # @param message [String] Error message
+      # @param location [Location] Error location
       def raise_error(message, location)
         raise_syntax_error(message, location: location)
       end
 
       private
 
-      def handle_complex_object(obj)
-        if obj.class.instance_methods.include?(:to_ast_node)
+      def create_literal(value)
+        Literal.new(value, loc: current_location)
+      end
+
+      def create_list(array)
+        elements = array.map { |element| ensure_syntax(element) }
+        ListExpression.new(elements, loc: current_location)
+      end
+
+      def handle_custom_object(obj)
+        if obj.respond_to?(:to_ast_node)
           obj.to_ast_node
         else
-          raise_syntax_error("Invalid expression: #{obj.inspect}", location: @context.current_location)
+          raise_invalid_expression_error(obj)
         end
       end
+
+      def validate_reference_name(name)
+        unless name.is_a?(Symbol)
+          raise_syntax_error(
+            "Reference name must be a symbol, got #{name.class}",
+            location: current_location
+          )
+        end
+      end
+
+      def validate_function_name(fn_name)
+        unless fn_name.is_a?(Symbol)
+          raise_syntax_error(
+            "Function name must be a symbol, got #{fn_name.class}",
+            location: current_location
+          )
+        end
+      end
+
+      def convert_arguments(args)
+        args.map { |arg| ensure_syntax(arg) }
+      end
+
+      def raise_invalid_expression_error(obj)
+        raise_syntax_error(
+          "Cannot convert #{obj.class} to AST node. " \
+          "Value: #{obj.inspect}",
+          location: current_location
+        )
+      end
+
+      def current_location
+        @context.current_location
+      end
     end
   end
-end
+end

data/lib/kumi/parser/parser.rb

@@ -36,6 +36,8 @@ module Kumi
         rule_block.binding.eval("using Kumi::Parser::Sugar::ExpressionRefinement")
         rule_block.binding.eval("using Kumi::Parser::Sugar::NumericRefinement")
         rule_block.binding.eval("using Kumi::Parser::Sugar::StringRefinement")
+        rule_block.binding.eval("using Kumi::Parser::Sugar::ArrayRefinement")
+        rule_block.binding.eval("using Kumi::Parser::Sugar::ModuleRefinement")
       rescue RuntimeError, NoMethodError
         # Refinements disabled in method scope - continue without them
       end

data/lib/kumi/parser/sugar.rb

@@ -5,10 +5,22 @@ module Kumi
     module Sugar
       include Syntax
 
-      ARITHMETIC_OPS = { :+ => :add, :- => :subtract, :* => :multiply,
-                         :/ => :divide, :% => :modulo, :** => :power }.freeze
+      ARITHMETIC_OPS = {
+        :+ => :add, :- => :subtract, :* => :multiply,
+        :/ => :divide, :% => :modulo, :** => :power
+      }.freeze
+
       COMPARISON_OPS = %i[< <= > >= == !=].freeze
-      LITERAL_TYPES = [Integer, String, Symbol, TrueClass, FalseClass, Float, Regexp].freeze
+
+      LITERAL_TYPES = [
+        Integer, String, Symbol, TrueClass, FalseClass, Float, Regexp
+      ].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 Literal.new(obj) if LITERAL_TYPES.any? { |type| obj.is_a?(type) }
@@ -22,32 +34,60 @@ module Kumi
         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)
+        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)
-              Syntax::CallExpression.new(op_name, [self, other_node])
+              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)
-              Syntax::CallExpression.new(op, [self, other_node])
+              Sugar.create_call_expression(op, [self, other_node])
             end
           end
 
+          # Array access
           def [](index)
-            Syntax::CallExpression.new(:at, [self, Sugar.ensure_literal(index)])
+            Sugar.create_call_expression(:at, [self, Sugar.ensure_literal(index)])
           end
 
+          # Unary minus
           def -@
-            Syntax::CallExpression.new(:subtract, [Sugar.ensure_literal(0), self])
+            Sugar.create_call_expression(:subtract, [Sugar.ensure_literal(0), self])
           end
 
+          # Logical operations
           def &(other)
-            Syntax::CallExpression.new(:and, [self, Sugar.ensure_literal(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
@@ -55,22 +95,24 @@ module Kumi
       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 = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
-                  Syntax::CallExpression.new(op_name, [Syntax::Literal.new(self), other_node])
+                  other_node = Sugar.ensure_literal(other)
+                  Sugar.create_call_expression(op_name, [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 = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
-                  Syntax::CallExpression.new(op, [Syntax::Literal.new(self), other_node])
+                  other_node = Sugar.ensure_literal(other)
+                  Sugar.create_call_expression(op, [Syntax::Literal.new(self), other_node])
                 else
                   super(other)
                 end
@@ -84,8 +126,8 @@ module Kumi
         refine String do
           def +(other)
             if Sugar.syntax_expression?(other)
-              other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
-              Syntax::CallExpression.new(:concat, [Syntax::Literal.new(self), other_node])
+              other_node = Sugar.ensure_literal(other)
+              Sugar.create_call_expression(:concat, [Syntax::Literal.new(self), other_node])
             else
               super
             end
@@ -94,8 +136,8 @@ module Kumi
           %i[== !=].each do |op|
             define_method(op) do |other|
               if Sugar.syntax_expression?(other)
-                other_node = other.respond_to?(:to_ast_node) ? other.to_ast_node : other
-                Syntax::CallExpression.new(op, [Syntax::Literal.new(self), other_node])
+                other_node = Sugar.ensure_literal(other)
+                Sugar.create_call_expression(op, [Syntax::Literal.new(self), other_node])
               else
                 super(other)
               end
@@ -103,6 +145,65 @@ module Kumi
           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) }
+            Syntax::ListExpression.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
     end
   end
 end

data/lib/kumi/schema.rb

@@ -4,6 +4,8 @@ require "ostruct"
 
 module Kumi
   module Schema
+    attr_reader :__syntax_tree__, :__analyzer_result__, :__compiled_schema__
+
     Inspector = Struct.new(:syntax_tree, :analyzer_result, :compiled_schema) do
       def inspect
         "#<#{self.class} syntax_tree: #{syntax_tree.inspect}, analyzer_result: #{analyzer_result.inspect}, schema: #{schema.inspect}>"
@@ -19,7 +21,7 @@ module Kumi
 
       raise Errors::InputValidationError, violations unless violations.empty?
 
-      SchemaInstance.new(@__compiled_schema__, @__analyzer_result__.definitions, context)
+      SchemaInstance.new(@__compiled_schema__, @__analyzer_result__, context)
     end
 
     def explain(context, *keys)