kumi 0.0.9 → 0.0.10

data/docs/features/javascript-transpiler.md

@@ -0,0 +1,148 @@
+# JavaScript Transpiler
+
+Transpiles compiled schemas to standalone JavaScript code.
+
+## Usage
+
+### Export Schema
+
+```ruby
+class TaxCalculator
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      float :income
+      string :filing_status
+    end
+    
+    trait :single, input.filing_status == "single"
+    
+    value :std_deduction do
+      on single, 14_600
+      base 29_200
+    end
+    
+    value :taxable_income, fn(:max, [input.income - std_deduction, 0])
+    value :tax_owed, taxable_income * 0.22
+  end
+end
+
+Kumi::Js.export_to_file(TaxCalculator, "tax-calculator.js")
+```
+
+### Use in JavaScript
+
+```javascript
+const { schema } = require('./tax-calculator.js');
+
+const taxpayer = {
+  income: 75000,
+  filing_status: "single"
+};
+
+const calculator = schema.from(taxpayer);
+console.log(calculator.fetch('tax_owed'));
+
+const results = calculator.slice('taxable_income', 'tax_owed');
+```
+
+## Export Methods
+
+### Command Line
+
+```bash
+bundle exec kumi --export-js output.js SchemaClass
+```
+
+### Programmatic
+
+```ruby
+Kumi::Js.export_to_file(MySchema, "schema.js")
+
+js_code = Kumi::Js.compile(MySchema)
+File.write("output.js", js_code)
+```
+
+## JavaScript API
+
+### schema.from(input)
+
+Creates runner instance.
+
+```javascript
+const runner = schema.from({ income: 50000, status: "single" });
+```
+
+### runner.fetch(key)
+
+Returns computed value. Results are cached.
+
+```javascript
+const tax = runner.fetch('tax_owed');
+```
+
+### runner.slice(...keys)
+
+Returns multiple values.
+
+```javascript
+const results = runner.slice('taxable_income', 'tax_owed');
+// Returns: { taxable_income: 35400, tax_owed: 7788 }
+```
+
+### runner.functionsUsed
+
+Array of functions used by the schema.
+
+```javascript
+console.log(runner.functionsUsed); // ["max", "subtract", "multiply"]
+```
+
+## Function Optimization
+
+The transpiler only includes functions actually used by the schema.
+
+Example schema using 4 functions generates ~3 KB instead of ~8 KB with all 67 functions.
+
+## Browser Compatibility
+
+- ES6+ (Chrome 60+, Firefox 55+, Safari 10+) 
+- Modern bundlers (Webpack, Rollup, Vite)
+- Node.js 12+
+
+## Limitations
+
+- No `explain()` method (Ruby only)
+- Custom Ruby functions need JavaScript equivalents
+
+## Module Formats
+
+Generated JavaScript supports:
+- CommonJS (`require()`)
+- ES Modules (`import`) 
+- Global variables (browser)
+
+## Minification
+
+Use production minifiers like Terser or UglifyJS for smaller bundles.
+
+## Dual Mode Validation
+
+Set `KUMI_DUAL_MODE=true` to automatically execute both Ruby and JavaScript versions and validate they produce identical results:
+
+```bash
+KUMI_DUAL_MODE=true ruby my_script.rb
+```
+
+Every calculation is validated in real-time. Mismatches throw detailed error reports with both results for debugging.
+
+## Error Handling
+
+```javascript
+try {
+  const runner = schema.from({ invalid: "data" });
+} catch (error) {
+  console.error(error.message);
+}
+```

data/docs/features/performance.md

@@ -1,8 +1,6 @@
 # Performance
 
-TODO: Add benchmark data
-
-Processes large schemas with optimized algorithms for analysis, compilation, and execution.
+Analysis, compilation, and execution performance for large schemas.
 
 ## Execution Model
 

data/docs/schema_metadata.md

@@ -1,6 +1,6 @@
 # Schema Metadata
 
-Kumi's SchemaMetadata interface provides structured access to analyzed schema information for building external tools like form generators, documentation systems, and analysis utilities.
+Kumi's SchemaMetadata interface accesses analyzed schema information for building external tools like form generators, documentation systems, and analysis utilities.
 
 ## Primary Interface
 
@@ -10,7 +10,7 @@ SchemaMetadata is the main interface for extracting metadata from Kumi schemas:
 metadata = MySchema.schema_metadata
 ```
 
-See the comprehensive API documentation in the SchemaMetadata class for detailed method documentation, examples, and usage patterns.
+See the API documentation in the SchemaMetadata class for method documentation, examples, and usage patterns.
 
 ## Processed Metadata (Tool-Friendly)
 
@@ -83,24 +83,24 @@ metadata.values
 # }
 ```
 
-### Clean Public Interface Examples
+### Public Interface Examples
 ```ruby
-# Processed dependency information (clean hashes)
+# Processed dependency information
 metadata.dependencies
 # => { :tax_amount => [{ to: :income, conditional: false }, { to: :tax_rate, conditional: false }] }
 
-# Processed declaration metadata (clean hashes)
+# Processed declaration metadata
 metadata.declarations  
 # => { :adult => { type: :trait, expression: ">=(input.age, 18)" }, :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" } }
 
-# Type inference results (clean data)
+# Type inference results
 metadata.inferred_types
 # => { :adult => :boolean, :tax_amount => :float, :item_totals => { array: :float } }
 ```
 
 ### Raw Analyzer State (Advanced Usage)
 ```ruby
-# Complete raw state hash with internal objects (AST nodes, Edge objects)
+# Raw state hash with internal objects (AST nodes, Edge objects)
 metadata.analyzer_state
 # => { declarations: {AST nodes...}, dependencies: {Edge objects...}, ... }
 ```

data/examples/game_of_life.rb

@@ -1,19 +1,17 @@
-$LOAD_PATH.unshift(File.join(__dir__, "..", "lib"))
 require "kumi"
 
-NEIGHBOR_DELTAS = [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]]
 begin
   # in a block so we dont define this globally
   def neighbor_cells_sum_method(cells, row, col, height, width)
     # Calculate neighbor indices with wraparound
-    NEIGHBOR_DELTAS.map do |dr, dc|
+    [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]].map do |dr, dc|
       neighbor_row = (row + dr) % height
       neighbor_col = (col + dc) % width
       neighbor_index = (neighbor_row * width) + neighbor_col
       cells[neighbor_index]
     end.sum
   end
-  Kumi::Core::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+  Kumi::Registry.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/lib/kumi/analyzer.rb

@@ -4,8 +4,6 @@ module Kumi
   module Analyzer
     Result = Struct.new(:definitions, :dependency_graph, :leaf_map, :topo_order, :decl_types, :state, keyword_init: true)
 
-    module_function
-
     DEFAULT_PASSES = [
       Core::Analyzer::Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
       Core::Analyzer::Passes::InputCollector,                  # 2. Collects field metadata from input declarations.

data/lib/kumi/compiler.rb

@@ -2,152 +2,18 @@
 
 module Kumi
   # Compiles an analyzed schema into executable lambdas
-  class Compiler
-    # ExprCompilers holds per-node compile implementations
-    module ExprCompilers
-      def compile_literal(expr)
-        v = expr.value
-        ->(_ctx) { v }
-      end
-
-      def compile_field_node(expr)
-        compile_field(expr)
-      end
-
-      def compile_element_field_reference(expr)
-        path = expr.path
-
-        lambda do |ctx|
-          # Start with the top-level collection from the context.
-          collection = ctx[path.first]
-
-          # Recursively map over the nested collections.
-          # The `dig_and_map` helper will handle any level of nesting.
-          dig_and_map(collection, path[1..])
-        end
-      end
-
-      def compile_binding_node(expr)
-        name = expr.name
-        # Handle forward references in cycles by deferring binding lookup to runtime
-        lambda do |ctx|
-          fn = @bindings[name].last
-          fn.call(ctx)
-        end
-      end
-
-      def compile_list(expr)
-        fns = expr.elements.map { |e| compile_expr(e) }
-        ->(ctx) { fns.map { |fn| fn.call(ctx) } }
-      end
-
-      def compile_call(expr)
-        fn_name = expr.fn_name
-        arg_fns = expr.args.map { |a| compile_expr(a) }
-
-        # Check if this is a vectorized operation
-        if vectorized_operation?(expr)
-          ->(ctx) { invoke_vectorized_function(fn_name, arg_fns, ctx, expr.loc) }
-        else
-          ->(ctx) { invoke_function(fn_name, arg_fns, ctx, expr.loc) }
-        end
-      end
-
-      def compile_cascade(expr)
-        # Check if current declaration is vectorized
-        broadcast_meta = @analysis.state[:broadcasts]
-        is_vectorized = @current_declaration && broadcast_meta&.dig(:vectorized_operations, @current_declaration)
-
-        # For vectorized cascades, we need to transform conditions that use all?
-        pairs = if is_vectorized
-                  expr.cases.map do |c|
-                    condition_fn = transform_vectorized_condition(c.condition)
-                    result_fn = compile_expr(c.result)
-                    [condition_fn, result_fn]
-                  end
-                else
-                  expr.cases.map { |c| [compile_expr(c.condition), compile_expr(c.result)] }
-                end
-
-        if is_vectorized
-          lambda do |ctx|
-            # This cascade can be vectorized - check if we actually need to at runtime
-            # Evaluate all conditions and results to check for arrays
-            cond_results = pairs.map { |cond, _res| cond.call(ctx) }
-            res_results = pairs.map { |_cond, res| res.call(ctx) }
-
-            # Check if any conditions or results are arrays (vectorized)
-            has_vectorized_data = (cond_results + res_results).any?(Array)
-
-            if has_vectorized_data
-              # Apply element-wise cascade evaluation
-              array_length = cond_results.find { |v| v.is_a?(Array) }&.length ||
-                             res_results.find { |v| v.is_a?(Array) }&.length || 1
-
-              (0...array_length).map do |i|
-                pairs.each_with_index do |(_cond, _res), pair_idx|
-                  cond_val = cond_results[pair_idx].is_a?(Array) ? cond_results[pair_idx][i] : cond_results[pair_idx]
-
-                  if cond_val
-                    res_val = res_results[pair_idx].is_a?(Array) ? res_results[pair_idx][i] : res_results[pair_idx]
-                    break res_val
-                  end
-                end || nil
-              end
-            else
-              # All data is scalar - use regular cascade evaluation
-              pairs.each_with_index do |(_cond, _res), pair_idx|
-                return res_results[pair_idx] if cond_results[pair_idx]
-              end
-              nil
-            end
-          end
-        else
-          lambda do |ctx|
-            pairs.each { |cond, res| return res.call(ctx) if cond.call(ctx) }
-            nil
-          end
-        end
-      end
-
-      def transform_vectorized_condition(condition_expr)
-        # If this is fn(:all?, [trait_ref]), extract the trait_ref for vectorized cascades
-        if condition_expr.is_a?(Kumi::Syntax::CallExpression) &&
-           condition_expr.fn_name == :all? &&
-           condition_expr.args.length == 1
-
-          arg = condition_expr.args.first
-          if arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.length == 1
-            trait_ref = arg.elements.first
-            return compile_expr(trait_ref)
-          end
-        end
-
-        # Otherwise compile normally
-        compile_expr(condition_expr)
-      end
-    end
-
-    include ExprCompilers
-
-    # 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
+  class Compiler < Core::CompilerBase
+    include Kumi::Core::Compiler::ReferenceCompiler
+    include Kumi::Core::Compiler::PathTraversalCompiler
+    include Kumi::Core::Compiler::ExpressionCompiler
+    include Kumi::Core::Compiler::FunctionInvoker
 
     def self.compile(schema, analyzer:)
       new(schema, analyzer).compile
     end
 
     def initialize(schema, analyzer)
-      @schema = schema
-      @analysis = analyzer
+      super
       @bindings = {}
     end
 
@@ -160,140 +26,5 @@ module Kumi
 
       Core::CompiledSchema.new(@bindings.freeze)
     end
-
-    private
-
-    def build_index
-      @index = {}
-      @schema.attributes.each { |a| @index[a.name] = a }
-      @schema.traits.each     { |t| @index[t.name] = t }
-    end
-
-    def dig_and_map(collection, path_segments)
-      return collection unless collection.is_a?(Array)
-
-      current_segment = path_segments.first
-      remaining_segments = path_segments[1..]
-
-      collection.map do |element|
-        value = element[current_segment]
-
-        # If there are more segments, recurse. Otherwise, return the value.
-        if remaining_segments.empty?
-          value
-        else
-          dig_and_map(value, remaining_segments)
-        end
-      end
-    end
-
-    def compile_declaration(decl)
-      @current_declaration = decl.name
-      kind = decl.is_a?(Kumi::Syntax::TraitDeclaration) ? :trait : :attr
-      fn = compile_expr(decl.expression)
-      @bindings[decl.name] = [kind, fn]
-      @current_declaration = nil
-    end
-
-    # Dispatch to the appropriate compile_* method
-    def compile_expr(expr)
-      method = DISPATCH.fetch(expr.class)
-      send(method, expr)
-    end
-
-    def compile_field(node)
-      name = node.name
-      loc  = node.loc
-      lambda do |ctx|
-        return ctx[name] if ctx.respond_to?(:key?) && ctx.key?(name)
-
-        raise Errors::RuntimeError,
-              "Key '#{name}' not found at #{loc}. Available: #{ctx.respond_to?(:keys) ? ctx.keys.join(', ') : 'N/A'}"
-      end
-    end
-
-    def vectorized_operation?(expr)
-      # Check if this operation uses vectorized inputs
-      broadcast_meta = @analysis.state[:broadcasts]
-      return false unless broadcast_meta
-
-      # Reduction functions are NOT vectorized operations - they consume arrays
-      return false if Kumi::Registry.reducer?(expr.fn_name)
-
-      expr.args.any? do |arg|
-        case arg
-        when Kumi::Syntax::InputElementReference
-          broadcast_meta[:array_fields]&.key?(arg.path.first)
-        when Kumi::Syntax::DeclarationReference
-          broadcast_meta[:vectorized_operations]&.key?(arg.name)
-        else
-          false
-        end
-      end
-    end
-
-    def invoke_vectorized_function(name, arg_fns, ctx, loc)
-      # Evaluate arguments
-      values = arg_fns.map { |fn| fn.call(ctx) }
-
-      # Check if any argument is vectorized (array)
-      has_vectorized_args = values.any?(Array)
-
-      if has_vectorized_args
-        # Apply function with broadcasting to all vectorized arguments
-        vectorized_function_call(name, values)
-      else
-        # All arguments are scalars - regular function call
-        fn = Kumi::Registry.fetch(name)
-        fn.call(*values)
-      end
-    rescue StandardError => e
-      enhanced_message = "Error calling fn(:#{name}) at #{loc}: #{e.message}"
-      runtime_error = Errors::RuntimeError.new(enhanced_message)
-      runtime_error.set_backtrace(e.backtrace)
-      runtime_error.define_singleton_method(:cause) { e }
-      raise runtime_error
-    end
-
-    def vectorized_function_call(fn_name, values)
-      # Get the function from registry
-      fn = Kumi::Registry.fetch(fn_name)
-
-      # Find array dimensions for broadcasting
-      array_values = values.select { |v| v.is_a?(Array) }
-      return fn.call(*values) if array_values.empty?
-
-      # All arrays should have the same length (validation could be added)
-      array_length = array_values.first.size
-
-      # Broadcast and apply function element-wise
-      (0...array_length).map do |i|
-        element_args = values.map do |v|
-          v.is_a?(Array) ? v[i] : v # Broadcast scalars
-        end
-        fn.call(*element_args)
-      end
-    end
-
-    def invoke_function(name, arg_fns, ctx, loc)
-      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::Core::Errors::Error)
-        # Re-raise Kumi errors with enhanced message but preserve type
-        e.define_singleton_method(:message) { enhanced_message }
-        raise e
-      else
-        # For non-Kumi errors, wrap in RuntimeError but preserve original error info
-        runtime_error = Errors::RuntimeError.new(enhanced_message)
-        runtime_error.set_backtrace(e.backtrace)
-        runtime_error.define_singleton_method(:cause) { e }
-        raise runtime_error
-      end
-    end
   end
 end