kumi 0.0.29 → 0.0.30

data/lib/kumi/doc_generator/formatters/markdown.rb

@@ -29,7 +29,7 @@ module Kumi
         def group_by_id(docs)
           result = {}
           docs.each do |alias_name, entry|
-            id = entry['id']
+            id = entry["id"]
             result[id] ||= []
             result[id] << alias_name
           end
@@ -49,30 +49,28 @@ module Kumi
 
           lines << "- **Arity:** #{entry['arity']}"
 
-          if entry['dtype']
-            dtype_str = format_dtype(entry['dtype'])
+          if entry["dtype"]
+            dtype_str = format_dtype(entry["dtype"])
             lines << "- **Type:** #{dtype_str}"
           end
 
-          if is_reducer?(entry)
-            lines << "- **Behavior:** Reduces a dimension `[D] -> T`"
-          end
+          lines << "- **Behavior:** Reduces a dimension `[D] -> T`" if is_reducer?(entry)
           lines << ""
 
-          if entry['params'] && !entry['params'].empty?
+          if entry["params"] && !entry["params"].empty?
             lines << "### Parameters"
             lines << ""
-            entry['params'].each do |param|
-              lines << "- `#{param['name']}`#{param['description'] ? ": #{param['description']}" : ""}"
+            entry["params"].each do |param|
+              lines << "- `#{param['name']}`#{": #{param['description']}" if param['description']}"
             end
             lines << ""
           end
 
-          if entry['kernels'] && !entry['kernels'].empty?
+          if entry["kernels"] && !entry["kernels"].empty?
             lines << "### Implementations"
             lines << ""
-            entry['kernels'].each do |target, kernel|
-              lines.concat(format_kernel(target, kernel, entry['reduction_strategy']))
+            entry["kernels"].each do |target, kernel|
+              lines.concat(format_kernel(target, kernel, entry["reduction_strategy"]))
             end
           end
 
@@ -88,48 +86,48 @@ module Kumi
             lines << "`#{kernel['id']}`"
             lines << ""
 
-            has_identity = kernel['identity'] && !kernel['identity'].empty?
+            has_identity = kernel["identity"] && !kernel["identity"].empty?
 
-            if kernel['inline'] && has_identity
+            if kernel["inline"] && has_identity
               lines << "**Inline:** `#{escape_backticks(kernel['inline'])}` (`$0` = accumulator, `$1` = element)"
               lines << ""
             end
 
-            if kernel['impl']
+            if kernel["impl"]
               lines << "**Implementation:**"
               lines << ""
               lines << "```ruby"
-              lines << format_impl(kernel['impl'])
+              lines << format_impl(kernel["impl"])
               lines << "```"
               lines << ""
             end
 
-            if kernel['fold_inline']
+            if kernel["fold_inline"]
               lines << "**Fold:** `#{escape_backticks(kernel['fold_inline'])}`"
               lines << ""
             end
 
             if has_identity
               lines << "**Identity:**"
-              kernel['identity'].each do |type, value|
+              kernel["identity"].each do |type, value|
                 lines << "- #{type}: `#{value}`"
               end
               lines << ""
-            elsif kernel['inline']
+            elsif kernel["inline"]
               lines << "_Note: No identity value. First element initializes accumulator._"
               lines << ""
             end
 
             # Show reduction strategy if available
             if reduction_strategy
-              case reduction_strategy
-              when 'identity'
-                lines << "**Reduction:** Monoid operation with identity element"
-              when 'first_element'
-                lines << "**Reduction:** First element is initial value (no identity)"
-              else
-                lines << "**Reduction:** #{reduction_strategy}"
-              end
+              lines << case reduction_strategy
+                       when "identity"
+                         "**Reduction:** Monoid operation with identity element"
+                       when "first_element"
+                         "**Reduction:** First element is initial value (no identity)"
+                       else
+                         "**Reduction:** #{reduction_strategy}"
+                       end
               lines << ""
             end
           else
@@ -142,18 +140,18 @@ module Kumi
         def format_dtype(dtype)
           return "any" if dtype.nil?
 
-          case dtype['rule']
-          when 'same_as'
+          case dtype["rule"]
+          when "same_as"
             "same as `#{dtype['param']}`"
-          when 'scalar'
-            dtype['kind'] || 'scalar'
-          when 'promote'
-            params = Array(dtype['params']).join('`, `')
+          when "scalar"
+            dtype["kind"] || "scalar"
+          when "promote"
+            params = Array(dtype["params"]).join("`, `")
             "promoted from `#{params}`"
-          when 'element_of'
+          when "element_of"
             "element of `#{dtype['param']}`"
           else
-            dtype['rule']
+            dtype["rule"]
           end
         end
 
@@ -163,11 +161,11 @@ module Kumi
         end
 
         def escape_backticks(str)
-          str.gsub('`', '\`')
+          str.gsub("`", '\`')
         end
 
         def is_reducer?(entry)
-          entry['kind'] == 'reduce'
+          entry["kind"] == "reduce"
         end
       end
     end

data/lib/kumi/doc_generator/loader.rb

@@ -1,4 +1,4 @@
-require 'yaml'
+require "yaml"
 
 module Kumi
   module DocGenerator
@@ -10,11 +10,13 @@ module Kumi
 
       def load_functions
         return [] unless @functions_dir
+
         load_yaml_dir(@functions_dir)
       end
 
       def load_kernels
         return [] unless @kernels_dir
+
         load_yaml_dir(@kernels_dir)
       end
 
@@ -22,12 +24,12 @@ module Kumi
 
       def load_yaml_dir(dir_path)
         result = []
-        Dir.glob(File.join(dir_path, '**/*.yaml')).each do |file|
+        Dir.glob(File.join(dir_path, "**/*.yaml")).each do |file|
           data = YAML.load_file(file)
-          if data && data['functions']
-            result.concat(data['functions'])
-          elsif data && data['kernels']
-            result.concat(data['kernels'])
+          if data && data["functions"]
+            result.concat(data["functions"])
+          elsif data && data["kernels"]
+            result.concat(data["kernels"])
           end
         end
         result

data/lib/kumi/doc_generator/merger.rb

@@ -12,7 +12,7 @@ module Kumi
         result = {}
 
         functions.each do |fn|
-          aliases = fn['aliases'] || []
+          aliases = fn["aliases"] || []
           aliases.each do |alias_name|
             result[alias_name] = build_doc_entry(fn, kernels)
           end
@@ -26,27 +26,27 @@ module Kumi
       def build_doc_entry(function, kernels)
         kernel_map = {}
         kernels.each do |kernel|
-          if kernel['fn'] == function['id']
-            target = extract_target(kernel['id'])
+          if kernel["fn"] == function["id"]
+            target = extract_target(kernel["id"])
             kernel_map[target] = kernel
           end
         end
 
         {
-          'id' => function['id'],
-          'kind' => function['kind'],
-          'params' => function['params'] || [],
-          'arity' => (function['params'] || []).length,
-          'kernels' => kernel_map,
-          'dtype' => function['dtype'],
-          'aliases' => function['aliases'] || [],
-          'reduction_strategy' => function['reduction_strategy']
+          "id" => function["id"],
+          "kind" => function["kind"],
+          "params" => function["params"] || [],
+          "arity" => (function["params"] || []).length,
+          "kernels" => kernel_map,
+          "dtype" => function["dtype"],
+          "aliases" => function["aliases"] || [],
+          "reduction_strategy" => function["reduction_strategy"]
         }
       end
 
       def extract_target(kernel_id)
         # kernel_id format: "agg.sum:ruby:v1" -> "ruby"
-        parts = kernel_id.split(':')
+        parts = kernel_id.split(":")
         parts[1] if parts.length >= 2
       end
     end

data/lib/kumi/frontends/text.rb

@@ -30,9 +30,9 @@ module Kumi
           # Strip file:line:col prefix from e.message if it exists (from parser)
           # Also strip embedded "at FILE line=N column=M" to avoid duplication
           error_message = e.message
-            .sub(/^\S+:\d+:\d+:\s+/, '')
-            .gsub(/\s+at\s+\S+\s+line=\d+\s+column=\d+/, '')
-            .strip
+                           .sub(/^\S+:\d+:\d+:\s+/, "")
+                           .gsub(/\s+at\s+\S+\s+line=\d+\s+column=\d+/, "")
+                           .strip
           raise StandardError, "#{file_label}:#{line || '?'}:#{col || '?'}: #{error_message}\n#{snippet}"
         end
       end
@@ -41,9 +41,7 @@ module Kumi
         # Try to access Location object from exception
         if exception.respond_to?(:location) && exception.location
           loc = exception.location
-          if loc.respond_to?(:line) && loc.respond_to?(:column)
-            return [loc.line, loc.column]
-          end
+          return [loc.line, loc.column] if loc.respond_to?(:line) && loc.respond_to?(:column)
         end
 
         # Fall back to parsing error message if no Location object

data/lib/kumi/registry_v2/loader.rb

@@ -23,52 +23,52 @@ module Kumi
 
       # Build dtype rule from structured hash
       def build_dtype_rule_from_hash(spec)
-        rule_type = spec.fetch('rule') { raise "dtype hash requires 'rule' key" }
+        rule_type = spec.fetch("rule") { raise "dtype hash requires 'rule' key" }
 
         case rule_type
-        when 'same_as'
-          param = spec.fetch('param') { raise "same_as rule requires 'param' key" }
+        when "same_as"
+          param = spec.fetch("param") { raise "same_as rule requires 'param' key" }
           Kumi::Core::Functions::TypeRules.build_same_as(param.to_sym)
 
-        when 'promote'
-          params = spec.fetch('params') { raise "promote rule requires 'params' key" }
+        when "promote"
+          params = spec.fetch("params") { raise "promote rule requires 'params' key" }
           param_syms = Array(params).map { |p| p.to_sym }
           Kumi::Core::Functions::TypeRules.build_promote(*param_syms)
 
-        when 'element_of'
-          param = spec.fetch('param') { raise "element_of rule requires 'param' key" }
+        when "element_of"
+          param = spec.fetch("param") { raise "element_of rule requires 'param' key" }
           Kumi::Core::Functions::TypeRules.build_element_of(param.to_sym)
 
-        when 'unify'
-          param1 = spec.fetch('param1') { raise "unify rule requires 'param1' key" }
-          param2 = spec.fetch('param2') { raise "unify rule requires 'param2' key" }
+        when "unify"
+          param1 = spec.fetch("param1") { raise "unify rule requires 'param1' key" }
+          param2 = spec.fetch("param2") { raise "unify rule requires 'param2' key" }
           Kumi::Core::Functions::TypeRules.build_unify(param1.to_sym, param2.to_sym)
 
-        when 'common_type'
-          param = spec.fetch('param') { raise "common_type rule requires 'param' key" }
+        when "common_type"
+          param = spec.fetch("param") { raise "common_type rule requires 'param' key" }
           Kumi::Core::Functions::TypeRules.build_common_type(param.to_sym)
 
-        when 'array'
-          if spec.key?('element_type')
-            element_type_spec = spec['element_type']
+        when "array"
+          if spec.key?("element_type")
+            element_type_spec = spec["element_type"]
             element_type = if element_type_spec.is_a?(Hash)
-                            # Nested structured format
-                            build_dtype_rule_from_hash(element_type_spec).call({})
-                          else
-                            # String or symbol
-                            element_type_spec.to_sym
-                          end
+                             # Nested structured format
+                             build_dtype_rule_from_hash(element_type_spec).call({})
+                           else
+                             # String or symbol
+                             element_type_spec.to_sym
+                           end
             Kumi::Core::Functions::TypeRules.build_array(element_type)
-          elsif spec.key?('element_type_param')
-            element_type_param = spec['element_type_param'].to_sym
+          elsif spec.key?("element_type_param")
+            element_type_param = spec["element_type_param"].to_sym
             Kumi::Core::Functions::TypeRules.build_array(element_type_param)
           else
             raise "array rule requires either 'element_type' or 'element_type_param' key"
           end
 
-        when 'tuple'
-          if spec.key?('element_types')
-            element_types_spec = spec['element_types']
+        when "tuple"
+          if spec.key?("element_types")
+            element_types_spec = spec["element_types"]
             element_types = Array(element_types_spec).map do |et|
               if et.is_a?(Hash)
                 build_dtype_rule_from_hash(et).call({})
@@ -77,19 +77,18 @@ module Kumi
               end
             end
             Kumi::Core::Functions::TypeRules.build_tuple(*element_types)
-          elsif spec.key?('element_types_param')
-            element_types_param = spec['element_types_param'].to_sym
+          elsif spec.key?("element_types_param")
+            element_types_param = spec["element_types_param"].to_sym
             Kumi::Core::Functions::TypeRules.build_tuple(element_types_param)
           else
             raise "tuple rule requires either 'element_types' or 'element_types_param' key"
           end
 
-        when 'scalar'
-          kind = spec.fetch('kind') { raise "scalar rule requires 'kind' key" }
+        when "scalar"
+          kind = spec.fetch("kind") { raise "scalar rule requires 'kind' key" }
           kind_sym = kind.to_sym
-          unless Kumi::Core::Types::Validator.valid_kind?(kind_sym)
-            raise "scalar rule has unknown kind: #{kind}"
-          end
+          raise "scalar rule has unknown kind: #{kind}" unless Kumi::Core::Types::Validator.valid_kind?(kind_sym)
+
           Kumi::Core::Functions::TypeRules.build_scalar(kind_sym)
 
         else

data/lib/kumi/schema.rb

@@ -11,7 +11,7 @@ module Kumi
   module Schema
     # The `__syntax_tree__` is available on the class for introspection.
     attr_reader :__kumi_syntax_tree__, :__kumi_compiled_module__
-    alias_method :__syntax_tree__, :__kumi_syntax_tree__
+    alias __syntax_tree__ __kumi_syntax_tree__
 
     def build_syntax_tree(&)
       @__kumi_syntax_tree__ = Kumi::Core::RubyParser::Dsl.build_syntax_tree(&)
@@ -98,7 +98,7 @@ module Kumi
       end
     end
 
-    def compile_and_write_cache(cache_path, digest)
+    def compile_and_write_cache(cache_path, _digest)
       # 1. Extract the generated code from the final state object.
       compiler_output = @__kumi_analyzer_result__.state[:ruby_codegen_files]["codegen.rb"]
       raise "Compiler did not produce ruby_codegen_files" unless compiler_output

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.29"
+  VERSION = "0.0.30"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kumi
 version: !ruby/object:Gem::Version
-  version: 0.0.29
+  version: 0.0.30
 platform: ruby
 authors:
 - André Muta
@@ -10,33 +10,33 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: mutex_m
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.6.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
-  name: mutex_m
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 2.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 2.6.0
 email:
 - andremuta@gmail.com
 executables: []
@@ -82,22 +82,17 @@ files:
 - data/kernels/ruby/core/constructor.yaml
 - data/kernels/ruby/core/select.yaml
 - data/kernels/ruby/core/string.yaml
-- debug_ordering.rb
 - docs/ARCHITECTURE.md
 - docs/DEVELOPMENT.md
 - docs/FORM_SCHEMA.md
 - docs/FUNCTIONS.md
+- docs/GOLDEN_QUICK_START.md
+- docs/GOLDEN_TESTS.md
 - docs/OUTPUT_SCHEMA.md
 - docs/SYNTAX.md
 - docs/UNSAT_DETECTION.md
 - docs/VSCODE_EXTENSION.md
 - docs/functions-reference.json
-- examples/deep_schema_compilation_and_evaluation_benchmark.rb
-- examples/federal_tax_calculator_2024.rb
-- examples/game_of_life.rb
-- examples/simple_rpg_game.rb
-- examples/static_analysis_errors.rb
-- examples/wide_schema_compilation_and_evaluation_benchmark.rb
 - golden/array_element/expected.json
 - golden/array_element/expected/ast.txt
 - golden/array_element/expected/input_plan.txt
@@ -616,9 +611,13 @@ files:
 - lib/kumi/core/analyzer/constant_evaluator.rb
 - lib/kumi/core/analyzer/constant_folding_helpers.rb
 - lib/kumi/core/analyzer/debug.rb
+- lib/kumi/core/analyzer/execution_phase.rb
+- lib/kumi/core/analyzer/execution_result.rb
 - lib/kumi/core/analyzer/fn_aliases.rb
 - lib/kumi/core/analyzer/folder.rb
 - lib/kumi/core/analyzer/macro_expander.rb
+- lib/kumi/core/analyzer/pass_failure.rb
+- lib/kumi/core/analyzer/pass_manager.rb
 - lib/kumi/core/analyzer/passes/assemble_irv2_pass.rb
 - lib/kumi/core/analyzer/passes/attach_anchors_pass.rb
 - lib/kumi/core/analyzer/passes/attach_terminal_info_pass.rb

data/debug_ordering.rb

@@ -1,52 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require_relative 'spec/spec_helper'
-
-include PackTestHelper
-
-schema = <<~KUMI
-  schema do
-    input do
-      array :numbers do
-        integer :value
-      end
-    end
-    
-    value :total, fn(:sum, input.numbers.value)
-  end
-KUMI
-
-pack = pack_for(schema)
-generator = Kumi::Codegen::RubyV3::Generator.new(pack, module_name: "OrderingTest")
-
-generated_code = generator.render
-puts "=== GENERATED CODE ==="
-puts generated_code
-puts "======================"
-
-# Analyze the structure
-lines = generated_code.split("\n")
-while_line_idx = lines.find_index { |line| line.include?("while i0 < arr0.length") }
-end_line_idx = lines.find_index(while_line_idx) { |line| line.strip == "end" }
-
-puts "\n=== ANALYSIS ==="
-puts "While line at index: #{while_line_idx}"
-puts "End line at index: #{end_line_idx}"
-
-if while_line_idx && end_line_idx
-  loop_body_lines = lines[(while_line_idx + 1)...end_line_idx]
-  puts "Loop body lines:"
-  loop_body_lines.each_with_index do |line, i|
-    puts "  #{while_line_idx + 1 + i}: #{line}"
-  end
-  
-  value_access_line = loop_body_lines.find { |line| line.include?('a0["value"]') }
-  acc_add_line = loop_body_lines.find { |line| line.include?("acc_") && line.include?("+=") }
-  
-  puts "\nValue access line: #{value_access_line.inspect}"
-  puts "Acc add line: #{acc_add_line.inspect}"
-else
-  puts "Could not find while loop structure"
-end

data/examples/deep_schema_compilation_and_evaluation_benchmark.rb

@@ -1,106 +0,0 @@
-# Deep Schema Compilation and Evaluation Benchmark
-#
-# This benchmark measures Kumi's performance with increasingly deep dependency chains
-# to understand how compilation and evaluation times scale with schema depth.
-#
-# What it tests:
-# - Compilation time for schemas with deep dependency chains (50, 100, 150 levels)
-# - Evaluation performance for computing results through long dependency paths
-# - Stack-safe evaluation through iterative dependency resolution
-#
-# Schema structure:
-# - input: single integer seed
-# - values: chain of dependencies v0 = seed, v1 = v0 + 1, v2 = v1 + 2, ..., v_n = v_(n-1) + n
-# - traits: conditional checks at each level (value > threshold)
-# - cascade: final_result depends on first trait that evaluates to true
-#
-# Depth limits: Ruby stack overflow occurs around 200-300 levels depending on system,
-# so we test with conservative depths (50, 100, 150) to ensure reliability.
-#
-# Usage: bundle exec ruby examples/deep_schema_compilation_and_evaluation_benchmark.rb
-require "benchmark"
-require "benchmark/ips"
-require_relative "../lib/kumi"
-
-# ------------------------------------------------------------------
-# 1. Helper that builds a deep dependency chain schema
-# ------------------------------------------------------------------
-def build_deep_schema(depth)
-  Class.new do
-    extend Kumi::Schema
-
-    schema do
-      input { integer :seed }
-
-      # Build dependency chain: v0 = seed, v1 = v0 + 1, v2 = v1 + 2, etc.
-      value :v0, input.seed
-      
-      (1...depth).each do |i|
-        value :"v#{i}", fn(:add, ref(:"v#{i-1}"), i)
-      end
-
-      # Build traits that check if values exceed thresholds
-      # Use varying thresholds to create realistic evaluation scenarios
-      (0...depth).each do |i|
-        threshold = i * (i + 1) / 2 + 1000  # Quadratic growth to ensure variety
-        trait :"threshold_#{i}", fn(:>, ref(:"v#{i}"), threshold)
-      end
-
-      # Final cascade that finds first trait that's true
-      value :final_result do
-        (0...depth).each do |i|
-          on :"threshold_#{i}", fn(:multiply, ref(:"v#{i}"), 2)
-        end
-        base ref(:"v#{depth-1}")  # Default to final value
-      end
-    end
-  end
-end
-
-# Conservative depths to avoid Ruby stack overflow
-# Ruby stack depth limit is around 1000-2000 frames depending on the system
-# Keep depths well below this limit for reliable operation
-DEPTHS = [50, 100, 150, 200]
-
-# ------------------------------------------------------------------
-# 2. Measure compilation once per depth
-# ------------------------------------------------------------------
-compile_times = {}
-schemas       = {}
-
-DEPTHS.each do |d|
-  puts "\n--- Building #{d}-deep schema ---"
-  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-  schemas[d] = build_deep_schema(d)
-  compile_times[d] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
-end
-
-puts "=== compilation times ==="
-compile_times.each do |d, t|
-  puts format("compile %3d-deep: %6.1f ms", d, t * 1_000)
-end
-puts
-
-# ------------------------------------------------------------------
-# 3. Pure evaluation benchmark – no compilation inside the loop
-# ------------------------------------------------------------------
-Benchmark.ips do |x|
-  schemas.each do |d, schema|
-    runner = schema.from(seed: 0)          # memoised runner
-    x.report("eval #{d}-deep") { runner[:final_result] }
-  end
-  x.compare!
-end
-# Warming up --------------------------------------
-#         eval 50-deep   222.000 i/100ms
-#        eval 100-deep    57.000 i/100ms
-#        eval 150-deep    26.000 i/100ms
-# Calculating -------------------------------------
-#         eval 50-deep      2.166k (± 1.9%) i/s  (461.70 μs/i) -     10.878k in   5.024320s
-#        eval 100-deep    561.698 (± 1.4%) i/s    (1.78 ms/i) -      2.850k in   5.075057s
-#        eval 150-deep    253.732 (± 0.8%) i/s    (3.94 ms/i) -      1.274k in   5.021499s
-
-# Comparison:
-#         eval 50-deep:     2165.9 i/s
-#        eval 100-deep:      561.7 i/s - 3.86x  slower
-#        eval 150-deep:      253.7 i/s - 8.54x  slower