kumi 0.0.9 → 0.0.11

data/lib/kumi/core/compiler/accessors/each_indexed_accessor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class EachIndexedAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy, with_indices = true)
+            walker = build_each_walker(operations, path_key, policy, key_policy)
+            if with_indices
+              lambda do |data, &blk|
+                if blk
+                  walker.call(data, 0, [], ->(val, idx) { blk.call(val, idx) })
+                  nil
+                else
+                  out = []
+                  walker.call(data, 0, [], ->(val, idx) { out << [val, idx] })
+                  out
+                end
+              end
+            else
+              lambda do |data, &blk|
+                if blk
+                  walker.call(data, 0, [], ->(val, _idx) { blk.call(val) })
+                  nil
+                else
+                  out = []
+                  walker.call(data, 0, [], ->(val, _idx) { out << val })
+                  out
+                end
+              end
+            end
+          end
+
+          # Depth-first traversal yielding (value, nd_index)
+          def self.build_each_walker(operations, path_key, policy, key_policy)
+            mode = :each_indexed
+            walk = nil
+            walk = lambda do |node, pc, ndx, y|
+              if pc >= operations.length
+                y.call(node, ndx)
+                return
+              end
+
+              op = operations[pc]
+              case op[:type]
+              when :enter_hash
+                # If the *next* op is an array hop, relax to indifferent for that fetch
+                policy_for = next_enters_array?(operations, pc) ? :indifferent : key_policy
+                next_node = fetch_key(node, op[:key], policy_for)
+                if next_node == Base::MISSING
+                  case missing_key_action(policy)
+                  when :yield_nil then y.call(nil, ndx)
+                  when :skip      then return
+                  when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                  end
+                  return
+                end
+                walk.call(next_node, pc + 1, ndx, y)
+
+              when :enter_array
+                if node.nil?
+                  case missing_array_action(policy)
+                  when :yield_nil then y.call(nil, ndx)
+                  when :skip      then return
+                  when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                  end
+                  return
+                end
+                assert_array!(node, path_key, mode)
+                node.each_with_index { |child, i| walk.call(child, pc + 1, ndx + [i], y) }
+
+              else
+                raise "Unknown operation: #{op.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/accessors/materialize_accessor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class MaterializeAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :materialize
+            lambda do |data|
+              walk = nil
+              walk = lambda do |node, pc|
+                return node if pc >= operations.length
+
+                op = operations[pc]
+                case op[:type]
+                when :enter_hash
+                  assert_hash!(node, path_key, mode)
+                  preview_array = next_enters_array?(operations, pc)
+                  policy_for = preview_array ? :indifferent : key_policy
+                  next_node = fetch_key(node, op[:key], policy_for)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return preview_array ? [] : nil
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  walk.call(next_node, pc + 1)
+
+                when :enter_array
+                  if node.nil?
+                    case missing_array_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return []
+                    when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  assert_array!(node, path_key, mode)
+                  node.map { |child| walk.call(child, pc + 1) }
+
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+              walk.call(data, 0)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/accessors/ravel_accessor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        # Ravel: collect leaf elements reached by the op sequence.
+        # Invariants guaranteed by the planner for :ravel:
+        # - Every array edge along the path has an :enter_array op.
+        # - If the leaf container is an array, a terminal :enter_array is appended,
+        #   so the leaf we see here is the element, not the array.
+        class RavelAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :ravel
+
+            lambda do |data|
+              out = []
+
+              walk = nil
+              walk = lambda do |node, pc|
+                # Leaf: ops exhausted ⇒ emit this element (scalar/object/array element).
+                if pc >= operations.length
+                  out << node
+                  return
+                end
+
+                op = operations[pc]
+                case op[:type]
+                when :enter_hash
+                  # If the next step is an array, we don’t care about key symbol/string
+                  # (we’ll just iterate) → use indifferent lookup.
+                  preview_array = next_enters_array?(operations, pc)
+                  policy_for = preview_array ? :indifferent : key_policy
+
+                  next_node = fetch_key(node, op[:key], policy_for)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then out << nil
+                    when :skip      then return
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                    return
+                  end
+                  walk.call(next_node, pc + 1)
+
+                when :enter_array
+                  if node.nil?
+                    case missing_array_action(policy)
+                    when :yield_nil then out << nil
+                    when :skip      then return
+                    when :raise     then raise KeyError, "Missing array at '#{path_key}' (#{mode})"
+                    end
+                    return
+                  end
+                  assert_array!(node, path_key, mode)
+                  node.each { |child| walk.call(child, pc + 1) }
+
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+
+              walk.call(data, 0)
+              out
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler/accessors/read_accessor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Compiler
+      module Accessors
+        class ReadAccessor
+          extend Base
+
+          def self.build(operations, path_key, policy, key_policy)
+            mode = :read
+            lambda do |data|
+              node = data
+              operations.each do |op|
+                case op[:type]
+                when :enter_hash
+                  assert_hash!(node, path_key, mode)
+                  next_node = fetch_key(node, op[:key], key_policy)
+                  if next_node == Base::MISSING
+                    case missing_key_action(policy)
+                    when :yield_nil then return nil
+                    when :skip      then return nil
+                    when :raise     then raise KeyError, "Missing key '#{op[:key]}' at '#{path_key}' (#{mode})"
+                    end
+                  end
+                  node = next_node
+                when :enter_array
+                  # Should never be present for rank-0 plans
+                  raise TypeError, "Array encountered in :read accessor at '#{path_key}'"
+                else
+                  raise "Unknown operation: #{op.inspect}"
+                end
+              end
+              node
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/compiler_base.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    # Base compiler class with shared compilation logic between Ruby and JS compilers
+    class CompilerBase
+      # Map node classes to compiler methods
+      DISPATCH = {
+        Kumi::Syntax::Literal => :compile_literal,
+        Kumi::Syntax::InputReference => :compile_field_node,
+        Kumi::Syntax::InputElementReference => :compile_element_field_reference,
+        Kumi::Syntax::DeclarationReference => :compile_binding_node,
+        Kumi::Syntax::ArrayExpression => :compile_list,
+        Kumi::Syntax::CallExpression => :compile_call,
+        Kumi::Syntax::CascadeExpression => :compile_cascade
+      }.freeze
+
+      def initialize(syntax_tree, analyzer_result)
+        @schema = syntax_tree
+        @analysis = analyzer_result
+      end
+
+      # Shared compilation logic
+
+      def build_index
+        @index = {}
+        @schema.values.each { |a| @index[a.name] = a }
+        @schema.traits.each { |t| @index[t.name] = t }
+      end
+
+      def determine_operation_mode_for_path(_path)
+        # Use pre-computed operation mode from analysis
+        compilation_meta = @analysis.state[:broadcasts]&.dig(:compilation_metadata, @current_declaration)
+        compilation_meta&.dig(:operation_mode) || :broadcast
+      end
+
+      def vectorized_operation?(expr)
+        # Use pre-computed vectorization decision from analysis
+        compilation_meta = @analysis.state[:broadcasts]&.dig(:compilation_metadata, @current_declaration)
+        return false unless compilation_meta
+
+        # Check if current declaration is vectorized
+        if compilation_meta[:is_vectorized]
+          # For vectorized declarations, check if this specific operation should be vectorized
+          vectorized_ops = @analysis.state[:broadcasts][:vectorized_operations] || {}
+          current_decl_info = vectorized_ops[@current_declaration]
+
+          # For cascade declarations, check individual operations within them
+          return true if current_decl_info && current_decl_info[:operation] == expr.fn_name
+
+          # For cascade_with_vectorized_conditions_or_results, allow nested operations
+          return true if current_decl_info && current_decl_info[:source] == :cascade_with_vectorized_conditions_or_results
+
+          # Check if this is a direct vectorized operation
+          return true if current_decl_info && current_decl_info[:operation]
+        end
+
+        # Fallback: Reduction functions are NOT vectorized operations - they consume arrays
+        return false if Kumi::Registry.reducer?(expr.fn_name)
+
+        # Use pre-computed vectorization context for remaining cases
+        compilation_meta.dig(:vectorization_context, :needs_broadcasting) || false
+      end
+
+      def is_cascade_vectorized?(_expr)
+        # Use metadata to determine if this cascade is vectorized
+        broadcast_meta = @analysis.state[:broadcasts]
+        cascade_info = @current_declaration && broadcast_meta&.dig(:vectorized_operations, @current_declaration)
+        cascade_info && cascade_info[:source] == :cascade_with_vectorized_conditions_or_results
+      end
+
+      def get_cascade_compilation_metadata
+        compilation_meta = @analysis.state[:broadcasts]&.dig(:compilation_metadata, @current_declaration)
+        cascade_info = compilation_meta&.dig(:cascade_info) || {}
+        [compilation_meta, cascade_info]
+      end
+
+      def get_cascade_strategy
+        @analysis.state[:broadcasts][:cascade_strategies][@current_declaration]
+      end
+
+      def get_function_call_strategy
+        compilation_meta = @analysis.state[:broadcasts]&.dig(:compilation_metadata, @current_declaration)
+        compilation_meta&.dig(:function_call_strategy) || {}
+      end
+
+      def needs_flattening?
+        function_strategy = get_function_call_strategy
+        function_strategy[:flattening_required]
+      end
+
+      def get_flattening_info
+        @analysis.state[:broadcasts][:flattening_declarations][@current_declaration]
+      end
+
+      def get_flatten_argument_indices
+        compilation_meta = @analysis.state[:broadcasts]&.dig(:compilation_metadata, @current_declaration)
+        compilation_meta&.dig(:function_call_strategy, :flatten_argument_indices) || []
+      end
+
+      # Dispatch to the appropriate compile_* method
+      def compile_expr(expr)
+        method = DISPATCH.fetch(expr.class)
+        send(method, expr)
+      end
+
+      # Abstract methods to be implemented by subclasses
+      def compile_literal(expr)
+        raise NotImplementedError, "Subclasses must implement compile_literal"
+      end
+
+      def compile_field_node(expr)
+        raise NotImplementedError, "Subclasses must implement compile_field_node"
+      end
+
+      def compile_element_field_reference(expr)
+        raise NotImplementedError, "Subclasses must implement compile_element_field_reference"
+      end
+
+      def compile_binding_node(expr)
+        raise NotImplementedError, "Subclasses must implement compile_binding_node"
+      end
+
+      def compile_list(expr)
+        raise NotImplementedError, "Subclasses must implement compile_list"
+      end
+
+      def compile_call(expr)
+        raise NotImplementedError, "Subclasses must implement compile_call"
+      end
+
+      def compile_cascade(expr)
+        raise NotImplementedError, "Subclasses must implement compile_cascade"
+      end
+    end
+  end
+end

data/lib/kumi/core/error_reporter.rb

@@ -12,7 +12,7 @@ module Kumi
     # 4. Support both immediate raising and error accumulation patterns
     module ErrorReporter
       # Standard error structure for internal use
-      ErrorEntry = Struct.new(:location, :message, :type, :context, keyword_init: true) do
+      ErrorEntry = Struct.new(:location, :message, :type, :context, :backtrace, keyword_init: true) do
         def to_s
           location_str = format_location(location)
           "#{location_str}: #{message}"
@@ -47,12 +47,13 @@ module Kumi
       # @param type [Symbol] Optional error category (:syntax, :semantic, :type, etc.)
       # @param context [Hash] Optional additional context
       # @return [ErrorEntry] Structured error entry
-      def create_error(message, location: nil, type: :semantic, context: {})
+      def create_error(message, location: nil, type: :semantic, context: {}, backtrace: nil)
         ErrorEntry.new(
           location: location,
           message: message,
           type: type,
-          context: context
+          context: context,
+          backtrace: backtrace
         )
       end
 
@@ -76,8 +77,8 @@ module Kumi
       # @param error_class [Class] Exception class to raise
       # @param type [Symbol] Error category
       # @param context [Hash] Additional context
-      def raise_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, context: {})
-        entry = create_error(message, location: location, type: type, context: context)
+      def raise_error(message, location: nil, error_class: Errors::SemanticError, type: :semantic, backtrace: nil, context: {})
+        entry = create_error(message, location: location, type: type, context: context, backtrace: backtrace || caller)
         # Pass both the formatted message and the original location to the error constructor
         raise error_class.new(entry.to_s, location)
       end

data/lib/kumi/core/errors.rb

@@ -24,6 +24,8 @@ module Kumi
 
       class UnknownFunction < Error; end
 
+      class AnalysisError < Error; end
+
       class SemanticError < LocatedError; end
 
       class TypeError < SemanticError; end
@@ -32,6 +34,8 @@ module Kumi
 
       class SyntaxError < LocatedError; end
 
+      class CompilationError < Error; end
+
       class RuntimeError < Error; end
 
       class DomainViolationError < Error