kumi 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec2c56684edac64e9818bbf85de98e9855c3d50df80c490c8f868b3e9b701dab
-  data.tar.gz: d5246f98e10b0365b47f6a67fed5c3a4cbc77d5ad15905d93b046251965135f5
+  metadata.gz: 652ef5f59f7c4469c86ecda4add1f650121d75d333231ae50306a7bf2ce7725c
+  data.tar.gz: 367a335e09a9d5cefaecbfa8e870c99ac49153a771f2451e3cfa8f73531d0701
 SHA512:
-  metadata.gz: f71ba6867b72145247b5c1ea4c3b197f831996bf078798c6a9decdb4e047f83859e062e6a6411e2311d279f8a8cc03ca7e16ac194c9a27b84f8a55b67faa3fcb
-  data.tar.gz: 70c4dab6bf036da2d507f89c2d8e9d65a24da2685412d3e517a2b3c1696d200c294c512786c85bfccf9feca301e90e70a26999f5ed1528221331b55f77175c8d
+  metadata.gz: 2dece8cc4284177c7f45a97768ea0c228cf41210d85cff985850a5e98f64c4ce02cc2c97cc2a20897d1f192422390ad39357b0d883e4e6aebbae1d0abc41cfe8
+  data.tar.gz: cb817018fab35b9594053d5bbd7fa4adb31c79a92d7e968a2739f9ffd16d194a3a45aeb75b6fcc28743fadcd93da83c9227cfe81d14bb2f9d917c18e1fb5d16b

data/CLAUDE.md

@@ -62,7 +62,7 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 **Compiler** (`lib/kumi/compiler.rb`):
 - Transforms analyzed syntax tree into executable lambda functions
 - Maps each expression type to a compilation method
-- Handles function calls via `FunctionRegistry`
+- Handles function calls via `Kumi::Registry`
 - Produces `CompiledSchema` with executable bindings
 
 **Function Registry** (`lib/kumi/function_registry.rb`):

data/README.md

@@ -8,7 +8,6 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
 
-
 ## What can you build?
 
 Calculate U.S. federal taxes:
@@ -118,16 +117,14 @@ value :monthly_payment, fn(:pmt, rate: 0.05/12, nper: 36, pv: -loan_amount)
 ```
 Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIONS.md)
 
-These primitives are statically analyzed during schema definition to catch logical errors before runtime.
-
 </details>
 
 <details>
-<summary><strong>🔍 Static Analysis</strong> - Catch business logic errors at definition time</summary>
+<summary><strong>🔍 Static Analysis</strong> - Catch errors at definition time and provides rich metadata</summary>
 
 ### Static Analysis
 
-Kumi catches business logic errors that cause runtime failures or silent bugs:
+Kumi catches many types of business logic errors that cause runtime failures or silent bugs:
 
 ```ruby
 module InsurancePolicyPricer
@@ -361,6 +358,12 @@ The SchemaMetadata interface provides both processed metadata for tool developme
 
 </details>
 
+## Beyond Rules: What the Metadata Unlocks
+* **Auto-generated forms** – compile schema → field spec → React form
+* **Scenario explorer** – derive all trait combinations, Monte Carlo outcomes
+* **Coverage dashboard** – flag branches never hit in prod
+* **Schema diff** – highlight behaviour changes across versions
+
 ## Usage
 
 **Suitable for:**

data/examples/game_of_life.rb

@@ -13,7 +13,7 @@ begin
       cells[neighbor_index]
     end.sum
   end
-  Kumi::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+  Kumi::Core::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
                                                 return_type: :integer, arity: 5,
                                                 param_types: %i[array integer integer integer integer],
                                                 description: "Get neighbor cells for Conway's Game of Life")

data/examples/static_analysis_errors.rb

@@ -22,7 +22,7 @@ begin
       value :yearly_rate, monthly_rate * 12
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -48,7 +48,7 @@ begin
       end
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -71,7 +71,7 @@ begin
       value :invalid_sum, input.name + input.age
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -94,7 +94,7 @@ begin
       trait :impossible_score, input.score == 150
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -114,7 +114,7 @@ begin
       value :result, ref(:nonexistent_trait) ? 100 : 0
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -134,7 +134,7 @@ begin
       value :result, fn(:nonexistent_function, input.text)
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -162,7 +162,7 @@ begin
       value :result, ref(:undefined_declaration)
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → " + e.message.split("\n").join("\n   → ")
 end
 

data/lib/kumi/analyzer.rb

@@ -7,21 +7,21 @@ module Kumi
     module_function
 
     DEFAULT_PASSES = [
-      Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
-      Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
-      Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
-      Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
-      Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
-      Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
-      Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
-      Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
-      Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
-      Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
-      Passes::TypeChecker                      # 11. Validates types using inferred information.
+      Core::Analyzer::Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
+      Core::Analyzer::Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
+      Core::Analyzer::Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
+      Core::Analyzer::Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
+      Core::Analyzer::Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
+      Core::Analyzer::Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
+      Core::Analyzer::Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
+      Core::Analyzer::Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
+      Core::Analyzer::Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
+      Core::Analyzer::Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
+      Core::Analyzer::Passes::TypeChecker                      # 11. Validates types using inferred information.
     ].freeze
 
-    def analyze!(schema, passes: DEFAULT_PASSES, **opts)
-      state = AnalysisState.new(opts)
+    def self.analyze!(schema, passes: DEFAULT_PASSES, **opts)
+      state = Core::Analyzer::AnalysisState.new(opts)
       errors = []
 
       state = run_analysis_passes(schema, passes, state, errors)
@@ -35,7 +35,7 @@ module Kumi
         begin
           state = pass_instance.run(errors)
         rescue StandardError => e
-          errors << ErrorReporter.create_error(e.message, location: nil, type: :semantic)
+          errors << Core::ErrorReporter.create_error(e.message, location: nil, type: :semantic)
         end
       end
       state
@@ -62,7 +62,7 @@ module Kumi
     end
 
     # Handle both old and new error formats for backward compatibility
-    def format_errors(errors)
+    def self.format_errors(errors)
       return "" if errors.empty?
 
       errors.map(&:to_s).join("\n")

data/lib/kumi/compiler.rb

@@ -158,7 +158,7 @@ module Kumi
         compile_declaration(decl)
       end
 
-      CompiledSchema.new(@bindings.freeze)
+      Core::CompiledSchema.new(@bindings.freeze)
     end
 
     private
@@ -218,7 +218,7 @@ module Kumi
       return false unless broadcast_meta
 
       # Reduction functions are NOT vectorized operations - they consume arrays
-      return false if FunctionRegistry.reducer?(expr.fn_name)
+      return false if Kumi::Registry.reducer?(expr.fn_name)
 
       expr.args.any? do |arg|
         case arg
@@ -244,7 +244,7 @@ module Kumi
         vectorized_function_call(name, values)
       else
         # All arguments are scalars - regular function call
-        fn = FunctionRegistry.fetch(name)
+        fn = Kumi::Registry.fetch(name)
         fn.call(*values)
       end
     rescue StandardError => e
@@ -257,7 +257,7 @@ module Kumi
 
     def vectorized_function_call(fn_name, values)
       # Get the function from registry
-      fn = FunctionRegistry.fetch(fn_name)
+      fn = Kumi::Registry.fetch(fn_name)
 
       # Find array dimensions for broadcasting
       array_values = values.select { |v| v.is_a?(Array) }
@@ -276,14 +276,14 @@ module Kumi
     end
 
     def invoke_function(name, arg_fns, ctx, loc)
-      fn = FunctionRegistry.fetch(name)
+      fn = Kumi::Registry.fetch(name)
       values = arg_fns.map { |fn| fn.call(ctx) }
       fn.call(*values)
     rescue StandardError => e
       # Preserve original error class and backtrace while adding context
       enhanced_message = "Error calling fn(:#{name}) at #{loc}: #{e.message}"
 
-      if e.is_a?(Kumi::Errors::Error)
+      if e.is_a?(Kumi::Core::Errors::Error)
         # Re-raise Kumi errors with enhanced message but preserve type
         e.define_singleton_method(:message) { enhanced_message }
         raise e

data/lib/kumi/core/analyzer/analysis_state.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      # Simple immutable state wrapper to prevent accidental mutations between passes
+      class AnalysisState
+        def initialize(data = {})
+          @data = data.dup.freeze
+        end
+
+        # Get a value (same as hash access)
+        def [](key)
+          @data[key]
+        end
+
+        # Check if key exists (same as hash)
+        def key?(key)
+          @data.key?(key)
+        end
+
+        # Get all keys (same as hash)
+        def keys
+          @data.keys
+        end
+
+        # Create new state with additional data (simple and clean)
+        def with(key, value)
+          AnalysisState.new(@data.merge(key => value))
+        end
+
+        # Convert back to hash for final result
+        def to_h
+          @data.dup
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/constant_evaluator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      class ConstantEvaluator
+        include Syntax
+
+        def initialize(definitions)
+          @definitions = definitions
+          @memo = {}
+        end
+
+        OPERATORS = {
+          add: :+,
+          subtract: :-,
+          multiply: :*,
+          divide: :/
+        }.freeze
+
+        def evaluate(node, visited = Set.new)
+          return :unknown unless node
+          return @memo[node] if @memo.key?(node)
+          return node.value if node.is_a?(Literal)
+
+          result = case node
+                   when DeclarationReference then evaluate_binding(node, visited)
+                   when CallExpression then evaluate_call_expression(node, visited)
+                   else :unknown
+                   end
+
+          @memo[node] = result unless result == :unknown
+          result
+        end
+
+        private
+
+        def evaluate_binding(node, visited)
+          return :unknown if visited.include?(node.name)
+
+          visited << node.name
+          definition = @definitions[node.name]
+          return :unknown unless definition
+
+          evaluate(definition.expression, visited)
+        end
+
+        def evaluate_call_expression(node, visited)
+          return :unknown unless OPERATORS.key?(node.fn_name)
+
+          args = node.args.map { |arg| evaluate(arg, visited) }
+          return :unknown if args.any?(:unknown)
+
+          args.reduce(OPERATORS[node.fn_name])
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/broadcast_detector.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # Detects which operations should be broadcast over arrays
+        # DEPENDENCIES: :inputs, :declarations
+        # PRODUCES: :broadcasts
+        class BroadcastDetector < PassBase
+          def run(errors)
+            input_meta = get_state(:inputs) || {}
+            definitions = get_state(:declarations) || {}
+
+            # Find array fields with their element types
+            array_fields = find_array_fields(input_meta)
+
+            # Build compiler metadata
+            compiler_metadata = {
+              array_fields: array_fields,
+              vectorized_operations: {},
+              reduction_operations: {}
+            }
+
+            # Track which values are vectorized for type inference
+            vectorized_values = {}
+
+            # Analyze traits first, then values (to handle dependencies)
+            traits = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::TraitDeclaration) }
+            values = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::ValueDeclaration) }
+
+            (traits.to_a + values.to_a).each do |name, decl|
+              result = analyze_value_vectorization(name, decl.expression, array_fields, vectorized_values, errors)
+
+              case result[:type]
+              when :vectorized
+                compiler_metadata[:vectorized_operations][name] = result[:info]
+                # Store array source information for dimension checking
+                array_source = extract_array_source(result[:info], array_fields)
+                vectorized_values[name] = { vectorized: true, array_source: array_source }
+              when :reduction
+                compiler_metadata[:reduction_operations][name] = result[:info]
+                # Reduction produces scalar, not vectorized
+                vectorized_values[name] = { vectorized: false }
+              end
+            end
+
+            state.with(:broadcasts, compiler_metadata.freeze)
+          end
+
+          private
+
+          def find_array_fields(input_meta)
+            result = {}
+            input_meta.each do |name, meta|
+              next unless meta[:type] == :array && meta[:children]
+
+              result[name] = {
+                element_fields: meta[:children].keys,
+                element_types: meta[:children].transform_values { |v| v[:type] || :any }
+              }
+            end
+            result
+          end
+
+          def analyze_value_vectorization(name, expr, array_fields, vectorized_values, errors)
+            case expr
+            when Kumi::Syntax::InputElementReference
+              if array_fields.key?(expr.path.first)
+                { type: :vectorized, info: { source: :array_field_access, path: expr.path } }
+              else
+                { type: :scalar }
+              end
+
+            when Kumi::Syntax::DeclarationReference
+              # Check if this references a vectorized value
+              vector_info = vectorized_values[expr.name]
+              if vector_info && vector_info[:vectorized]
+                { type: :vectorized, info: { source: :vectorized_declaration, name: expr.name } }
+              else
+                { type: :scalar }
+              end
+
+            when Kumi::Syntax::CallExpression
+              analyze_call_vectorization(name, expr, array_fields, vectorized_values, errors)
+
+            when Kumi::Syntax::CascadeExpression
+              analyze_cascade_vectorization(name, expr, array_fields, vectorized_values, errors)
+
+            else
+              { type: :scalar }
+            end
+          end
+
+          def analyze_call_vectorization(_name, expr, array_fields, vectorized_values, errors)
+            # Check if this is a reduction function using function registry metadata
+            if Kumi::Registry.reducer?(expr.fn_name)
+              # Only treat as reduction if the argument is actually vectorized
+              arg_info = analyze_argument_vectorization(expr.args.first, array_fields, vectorized_values)
+              if arg_info[:vectorized]
+                { type: :reduction, info: { function: expr.fn_name, source: arg_info[:source] } }
+              else
+                # Not a vectorized reduction - just a regular function call
+                { type: :scalar }
+              end
+
+            else
+              # Special case: all?, any?, none? functions with vectorized trait arguments should be treated as vectorized
+              # for cascade condition purposes (they get transformed during compilation)
+              if %i[all? any? none?].include?(expr.fn_name) && expr.args.length == 1
+                arg = expr.args.first
+                if arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.length == 1
+                  trait_ref = arg.elements.first
+                  if trait_ref.is_a?(Kumi::Syntax::DeclarationReference) && vectorized_values[trait_ref.name]&.[](:vectorized)
+                    return { type: :vectorized, info: { source: :cascade_condition_with_vectorized_trait, trait: trait_ref.name } }
+                  end
+                end
+              end
+
+              # ANY function with vectorized arguments becomes vectorized (with broadcasting)
+              arg_infos = expr.args.map { |arg| analyze_argument_vectorization(arg, array_fields, vectorized_values) }
+
+              if arg_infos.any? { |info| info[:vectorized] }
+                # Check for dimension mismatches when multiple arguments are vectorized
+                vectorized_sources = arg_infos.select { |info| info[:vectorized] }.filter_map { |info| info[:array_source] }.uniq
+
+                if vectorized_sources.length > 1
+                  # Multiple different array sources - this is a dimension mismatch
+                  # Generate enhanced error message with type information
+                  enhanced_message = build_dimension_mismatch_error(expr, arg_infos, array_fields, vectorized_sources)
+
+                  report_error(errors, enhanced_message, location: expr.loc, type: :semantic)
+                  return { type: :scalar } # Treat as scalar to prevent further errors
+                end
+
+                # This is a vectorized operation - ANY function supports broadcasting
+                { type: :vectorized, info: {
+                  operation: expr.fn_name,
+                  vectorized_args: arg_infos.map.with_index { |info, i| [i, info[:vectorized]] }.to_h
+                } }
+              else
+                { type: :scalar }
+              end
+            end
+          end
+
+          def analyze_argument_vectorization(arg, array_fields, vectorized_values)
+            case arg
+            when Kumi::Syntax::InputElementReference
+              if array_fields.key?(arg.path.first)
+                { vectorized: true, source: :array_field, array_source: arg.path.first }
+              else
+                { vectorized: false }
+              end
+
+            when Kumi::Syntax::DeclarationReference
+              # Check if this references a vectorized value
+              vector_info = vectorized_values[arg.name]
+              if vector_info && vector_info[:vectorized]
+                array_source = vector_info[:array_source]
+                { vectorized: true, source: :vectorized_value, array_source: array_source }
+              else
+                { vectorized: false }
+              end
+
+            when Kumi::Syntax::CallExpression
+              # Recursively check
+              result = analyze_value_vectorization(nil, arg, array_fields, vectorized_values, [])
+              { vectorized: result[:type] == :vectorized, source: :expression }
+
+            else
+              { vectorized: false }
+            end
+          end
+
+          def extract_array_source(info, _array_fields)
+            case info[:source]
+            when :array_field_access
+              info[:path]&.first
+            when :cascade_condition_with_vectorized_trait
+              # For cascades, we'd need to trace back to the original source
+              nil # TODO: Could be enhanced to trace through trait dependencies
+            end
+          end
+
+          def analyze_cascade_vectorization(_name, expr, array_fields, vectorized_values, errors)
+            # A cascade is vectorized if:
+            # 1. Any of its result expressions are vectorized, OR
+            # 2. Any of its conditions reference vectorized values (traits or arrays)
+            vectorized_results = []
+            vectorized_conditions = []
+
+            expr.cases.each do |case_expr|
+              # Check if result is vectorized
+              result_info = analyze_value_vectorization(nil, case_expr.result, array_fields, vectorized_values, errors)
+              vectorized_results << (result_info[:type] == :vectorized)
+
+              # Check if condition is vectorized
+              condition_info = analyze_value_vectorization(nil, case_expr.condition, array_fields, vectorized_values, errors)
+              vectorized_conditions << (condition_info[:type] == :vectorized)
+            end
+
+            if vectorized_results.any? || vectorized_conditions.any?
+              { type: :vectorized, info: { source: :cascade_with_vectorized_conditions_or_results } }
+            else
+              { type: :scalar }
+            end
+          end
+
+          def build_dimension_mismatch_error(_expr, arg_infos, array_fields, vectorized_sources)
+            # Build detailed error message with type information
+            summary = "Cannot broadcast operation across arrays from different sources: #{vectorized_sources.join(', ')}. "
+
+            problem_desc = "Problem: Multiple operands are arrays from different sources:\n"
+
+            vectorized_args = arg_infos.select { |info| info[:vectorized] }
+            vectorized_args.each_with_index do |arg_info, index|
+              array_source = arg_info[:array_source]
+              next unless array_source && array_fields[array_source]
+
+              # Determine the type based on array field metadata
+              type_desc = determine_array_type(array_source, array_fields)
+              problem_desc += "  - Operand #{index + 1} resolves to #{type_desc} from array '#{array_source}'\n"
+            end
+
+            explanation = "Direct operations on arrays from different sources is ambiguous and not supported. " \
+                          "Vectorized operations can only work on fields from the same array input."
+
+            "#{summary}#{problem_desc}#{explanation}"
+          end
+
+          def determine_array_type(array_source, array_fields)
+            field_info = array_fields[array_source]
+            return "array(any)" unless field_info[:element_types]
+
+            # For nested arrays (like items.name where items is an array), this represents array(element_type)
+            element_types = field_info[:element_types].values.uniq
+            if element_types.length == 1
+              "array(#{element_types.first})"
+            else
+              "array(mixed)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/passes/declaration_validator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      module Passes
+        # RESPONSIBILITY: Perform local structural validation on each declaration
+        # DEPENDENCIES: :definitions
+        # PRODUCES: None (validation only)
+        # INTERFACE: new(schema, state).run(errors)
+        class DeclarationValidator < VisitorPass
+          def run(errors)
+            each_decl do |decl|
+              visit(decl) { |node| validate_node(node, errors) }
+            end
+            state
+          end
+
+          private
+
+          def validate_node(node, errors)
+            case node
+            when Kumi::Syntax::ValueDeclaration
+              validate_attribute(node, errors)
+            when Kumi::Syntax::TraitDeclaration
+              validate_trait(node, errors)
+            end
+          end
+
+          def validate_attribute(node, errors)
+            return unless node.expression.nil?
+
+            report_error(errors, "attribute `#{node.name}` requires an expression", location: node.loc)
+          end
+
+          def validate_trait(node, errors)
+            return if node.expression.is_a?(Kumi::Syntax::CallExpression)
+
+            report_error(errors, "trait `#{node.name}` must wrap a CallExpression", location: node.loc)
+          end
+        end
+      end
+    end
+  end
+end