kumi 0.0.9 → 0.0.11

data/README.md

@@ -5,7 +5,7 @@
 
 Kumi is a Declarative logic and rules engine framework with static analysis for Ruby.
 
-It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
+It handles complex, interdependent calculations with validation and consistency checking.
 
 
 ## What can you build?
@@ -59,14 +59,14 @@ result[:total_tax]   # => 21,491.00
 result[:after_tax]   # => 78,509.00
 ```
 
-Real tax calculation with brackets, deductions, and FICA caps. Validation happens during schema definition.
+Real tax calculation with brackets, deductions, and FICA caps. 
 
-Kumi is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
+Validation happens during schema definition.
 
 ## Installation
 
 ```bash
-# Requires Ruby 3.0+
+# Requires Ruby 3.1+
 # No external dependencies
 gem install kumi
 ```
@@ -74,7 +74,7 @@ gem install kumi
 ## Core Features
 
 <details>
-<summary><strong>📊 Schema Primitives</strong> - Four building blocks for business logic</summary>
+<summary><strong>Schema Primitives</strong> - Four building blocks for business logic</summary>
 
 ### Schema Primitives
 
@@ -96,7 +96,7 @@ value :tax_rate, 0.08
 value :tax_amount, subtotal * tax_rate
 ```
 
-**Traits** are boolean conditions that enable branching logic:
+**Traits** are boolean conditions for branching logic:
 ```ruby
 trait :bulk_order, input.quantity >= 100
 trait :premium_customer, input.tier == "premium"
@@ -109,7 +109,7 @@ value :discount do
 end
 ```
 
-**Functions** provide computational building blocks:
+**Functions** are computational building blocks:
 
 ```ruby
 value :final_price, [subtotal - discount_amount, 0].max
@@ -120,9 +120,13 @@ Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIO
 </details>
 
 <details>
-<summary><strong>🔍 Static Analysis</strong> - Catch errors at definition time and provides rich metadata</summary>
+<summary><strong>Analysis & Introspection</strong> - Static verification, runtime inspection, and metadata extraction</summary>
 
-### Static Analysis
+### Analysis & Introspection
+
+Kumi provides comprehensive analysis capabilities - catching errors at definition time and exposing schema structure for tooling and debugging.
+
+#### **Static Analysis: Catch Errors Early**
 
 Kumi catches many types of business logic errors that cause runtime failures or silent bugs:
 
@@ -203,7 +207,7 @@ end
 # ❌ Function arity error: divide expects 2 arguments, got 1
 ```
 
-**Bounded Recursion**: Kumi allows mutual recursion when cascade conditions are mutually exclusive:
+**Mutual Recursion**: Kumi supports mutual recursion when cascade conditions are mutually exclusive:
 
 ```ruby
 trait :is_forward, input.operation == "forward"
@@ -212,7 +216,7 @@ trait :is_reverse, input.operation == "reverse"
 # Safe mutual recursion - conditions are mutually exclusive
 value :forward_processor do
   on is_forward, input.value * 2        # Direct calculation
-  on is_reverse, reverse_processor + 10  # Delegates to reverse (safe)
+  on is_reverse, reveAnalysisrse_processor + 10  # Delegates to reverse (safe)
   base "invalid operation"
 end
 
@@ -230,168 +234,225 @@ end
 
 This compiles because `operation` can only be "forward" or "reverse", never both. Each recursion executes one step before hitting a direct calculation.
 
-</details>
+#### **Runtime Introspection: Debug and Understand**
 
-<details>
-<summary><strong>🔍 Array Broadcasting</strong> - Automatic vectorization over array fields</summary>
-
-### Array Broadcasting
-
-Kumi broadcasts operations over array fields for element-wise computation:
+**Explainability**: Trace exactly how any value is computed, step-by-step. This is invaluable for debugging complex logic and auditing results.
 
 ```ruby
-schema do
-  input do
-    array :line_items do
-      float   :price
-      integer :quantity
-      string  :category
-    end
-    float :tax_rate
-  end
-
-  # Element-wise computation - broadcasts over each item
-  value :subtotals, input.line_items.price * input.line_items.quantity
-  
-  # Element-wise traits - applied to each item
-  trait :is_taxable, (input.line_items.category != "digital")
-  
-  # Aggregation operations - consume arrays to produce scalars
-  value :total_subtotal, fn(:sum, subtotals)
-  value :item_count, fn(:size, input.line_items)
-end
+Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
+# => fed_tax = fed_calc[0]
+#    = (fed_calc = piecewise_sum(taxable_income, fed_breaks, fed_rates)
+#       = piecewise_sum(85_400, [11_600, 47_150, ...], [0.10, 0.12, ...])
+#       = [15_099.50, 0.22])
+#    = 15_099.50
 ```
 
-**Dimension Mismatch Detection**: Operations across different arrays generate error messages:
+#### **Schema Metadata API: Build Tooling**
 
-```ruby
-schema do
-  input do
-    array :items do
-      string :name
-    end
-    array :logs do  
-      string :user_name
-    end
-  end
+Programmatically access the analyzed structure of your schema to build tools like form generators, documentation sites, or custom validators.
 
-  # This generates an error
-  trait :same_name, input.items.name == input.logs.user_name
-end
+```ruby
+metadata = FederalTax2024.schema_metadata
 
-# Error:
-# Cannot broadcast operation across arrays from different sources: items, logs. 
-# Problem: Multiple operands are arrays from different sources:
-#   - Operand 1 resolves to array(string) from array 'items'
-#   - Operand 2 resolves to array(string) from array 'logs'
-# Direct operations on arrays from different sources is ambiguous and not supported.
-```
+# Processed, tool-friendly metadata
+metadata.inputs           # => { name: { type: :string, domain: ... } }
+metadata.values           # => { name: { dependencies: [...], expression: "..." } }
+metadata.traits           # => { name: { condition: "...", dependencies: [...] } }
 
-</details>
+# Raw analyzer state for deep analysis
+metadata.dependencies     # Dependency graph between all declarations
+metadata.evaluation_order # Topologically sorted computation order
 
-<details>
-<summary><strong>💾 Automatic Memoization</strong> - Each value computed exactly once</summary>
+# Export to standard formats
+metadata.to_h             # => Serializable hash for JSON/APIs
+metadata.to_json_schema   # => JSON Schema for input validation
+```
 
-### Automatic Memoization
+#### **AST Visualization: See the Structure**
 
-Each value is computed exactly once:
+For deep debugging, you can print the raw Abstract Syntax Tree (AST) of a schema.
 
 ```ruby
-runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
-
-# First access computes full dependency chain
-runner[:total_tax]     # => 53,155.20
-
-# Subsequent access uses cached values
-runner[:fed_tax]       # => 39,077.00 (cached)
-runner[:after_tax]     # => 196,844.80 (cached)
+puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
+# => (Root
+#      inputs: [
+#        (InputDeclaration :income :float)
+#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
+#      ]
+#      traits: [...]
+#      attributes: [...])
 ```
 
 </details>
 
 <details>
-<summary><strong>🔍 Introspection</strong> - See exactly how values are calculated</summary>
+<summary><strong>Hierarchical Broadcasting</strong> - Vectorization over nested data structures</summary>
+
+### Hierarchical Broadcasting
+
+Kumi broadcasts operations over hierarchical data structures with two complementary access modes for maximum flexibility.
 
-### Introspection
+See [docs/features/hierarchical-broadcasting.md](docs/features/hierarchical-broadcasting.md) for detailed documentation.
 
-Show how values are calculated:
+**Business Scenario**: E-commerce checkout with dynamic pricing rules
 
+> **"As an e-commerce platform, I need to calculate order totals with complex discount rules:**
+> - Premium members get 15% off electronics
+> - Bulk orders (5+ items) get 10% off that item
+> - Free shipping on orders over $100
+> - Calculate: item subtotals, total discounts, shipping, final total
+> 
+> **The challenge:** Each order has different items, quantities, categories, and customer tiers. The discount logic involves multiple conditions - some items qualify for multiple discounts, others for none. Traditional pricing code requires nested if-statements and manual calculations."
+
+**Kumi Solution** (16 lines of declarative pricing logic):
 ```ruby
-Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_status: "single"})
-# => fed_tax = fed_calc[0]
-#    = (fed_calc = piecewise_sum(taxable_income, fed_breaks, fed_rates)
-#       = piecewise_sum(85,400, [11,600, 47,150, ...], [0.10, 0.12, ...])
-#       = [15,099.50, 0.22])
-#    = 15,099.50
+module OrderPricing
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      array :items do
+        float   :price
+        integer :quantity
+        string  :category
+      end
+      string :customer_tier
+      float  :shipping_threshold
+    end
+    
+    # Calculate item subtotals and discount eligibility
+    value :subtotals, input.items.price * input.items.quantity
+    trait :electronics, input.items.category == "electronics"
+    trait :bulk_item, input.items.quantity >= 5
+    trait :premium_customer, input.customer_tier == "premium"
+    
+    # Apply layered discounts (premium + bulk can stack)
+    trait :premium_electronics, premium_customer & electronics
+    trait :stacked_discount, premium_electronics & bulk_item
+    
+    value :discounted_prices do
+      on stacked_discount, input.items.price * 0.75      # 15% + 10% = 25% off
+      on premium_electronics, input.items.price * 0.85   # 15% off
+      on bulk_item, input.items.price * 0.90             # 10% off
+      base input.items.price                              # No discount
+    end
+    
+    value :final_subtotals, discounted_prices * input.items.quantity
+    
+    # Order totals and conditional shipping
+    value :subtotal, fn(:sum, final_subtotals)
+    value :total_savings, fn(:sum, subtotals) - subtotal
+    value :shipping, subtotal > input.shipping_threshold ? 0.0 : 9.99
+    value :total, subtotal + shipping
+  end
+end
 ```
 
-**Debug AST Structure**: Visualize the parsed schema as S-expressions:
+**Mixed Access Modes**: Both object and element access can be used together in the same schema:
 
 ```ruby
-puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
-# => (Root
-#      inputs: [
-#        (InputDeclaration :income :float)
-#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
-#      ]
-#      traits: [...]
-#      attributes: [...])
+module UserAnalytics
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      # Object access mode - structured business data
+      array :users do
+        string :name
+        integer :age
+      end
+      
+      # Element access mode - multi-dimensional raw arrays
+      array :recent_purchases do
+        element :integer, :days_ago
+      end
+    end
+
+    # Object access works normally
+    value :user_names, input.users.name
+    value :avg_age, fn(:avg, input.users.age)
+    
+    # Element access handles nested arrays with progressive path traversal
+    value :all_purchase_days, fn(:flatten, input.recent_purchases.days_ago)
+    value :recent_flags, input.recent_purchases.days_ago < 5
+    trait :has_recent_purchase, fn(:any?, fn(:flatten, recent_flags))
+    
+    # Progressive dimensional analysis - each path level goes deeper
+    value :purchase_dimensions, [
+      fn(:size, input.recent_purchases),           # Number of purchase groups
+      fn(:size, input.recent_purchases.days_ago)  # Total individual purchase days
+    ]
+    
+    # Mixed usage in conditions
+    trait :adult_users, input.users.age >= 18
+    value :adult_count, fn(:count_if, adult_users)
+  end
+end
+
+# Works with mixed data structures
+result = UserAnalytics.from({
+  users: [{ name: "Alice", age: 25 }, { name: "Bob", age: 17 }],
+  recent_purchases: [[1, 3, 7], [2, 4], [10, 15]]  # Nested arrays
+})
+
+result[:user_names]          # => ["Alice", "Bob"]
+result[:has_recent_purchase] # => true (some purchases < 5 days ago)
+result[:adult_count]         # => 1
+result[:purchase_dimensions] # => [3, 8] (3 groups, 8 total days)
 ```
 
 </details>
 
 <details>
-<summary><strong>📋 Schema Metadata</strong> - Extract structured information for tooling</summary>
+<summary><strong>Memoization</strong> - Each value computed exactly once</summary>
 
-### Schema Metadata
+### Memoization
 
-Access structured metadata for building tools like form generators and dependency analyzers:
+Each value is computed exactly once:
 
 ```ruby
-metadata = FederalTax2024.schema_metadata
-
-# Processed metadata (tool-friendly)
-metadata.inputs           # Input field types and domains  
-metadata.values           # Value declarations with dependencies
-metadata.traits           # Trait conditions and metadata
-metadata.functions        # Function registry information
+runner = FederalTax2024.from(income: 250_000, filing_status: "married_joint")
 
-# Raw analyzer state (advanced usage)
-metadata.dependencies     # Dependency graph between declarations
-metadata.evaluation_order # Topologically sorted computation order
-metadata.inferred_types   # Type inference results
-metadata.declarations     # Raw AST declaration nodes
+# First access computes full dependency chain
+runner[:total_tax]     # => 53,155.20
 
-# Export formats
-metadata.to_h             # Serializable hash for JSON/APIs
-metadata.to_json_schema   # JSON Schema for input validation
+# Subsequent access uses cached values
+runner[:fed_tax]       # => 39,077.00 (cached)
+runner[:after_tax]     # => 196,844.80 (cached)
 ```
-
-The SchemaMetadata interface provides both processed metadata for tool development and raw analyzer state for advanced use cases. Complete documentation available in the SchemaMetadata class and [docs/schema_metadata.md](docs/schema_metadata.md).
-
 </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:**
 - Complex interdependent business rules
 - Tax calculation engines
 - Insurance premium calculators
-- Loan amortization schedules
 - Commission structures with complex tiers
 - Pricing engines with multiple discount rules
 
 **Not suitable for:**
-- Simple conditional statements
+- Basic conditional statements
 - Sequential procedural workflows  
-- Rules that change during execution
-- High-frequency real-time processing
+- High-frequency processing
+
+## JavaScript Transpiler
+
+Transpiles compiled schemas to standalone JavaScript code. See [docs/features/javascript-transpiler.md](docs/features/javascript-transpiler.md) for details.
+
+```ruby
+Kumi::Js.export_to_file(FederalTax2024, "federal-tax-2024.js")
+```
+
+```javascript
+const { schema } = require('./federal-tax-2024.js');
+const calculator = schema.from({ income: 100_000, filing_status: "single" });
+console.log(calculator.fetch('total_tax'));   // 21491
+```
+
+Generated JavaScript includes only functions used by the schema.
+
+All tests run in dual mode to verify compiled schemas produce identical results in both Ruby and JavaScript.
 
 ## Performance
 
@@ -400,6 +461,12 @@ Benchmarks on Linux with Ruby 3.3.8 on a Dell Latitude 7450:
 - 1,000 attributes:         **131,000/sec** (analysis <50ms)
 - 10,000 attributes:        **14,200/sec**  (analysis ~300ms)
 
+See [docs/features/performance.md](docs/features/performance.md) for detailed benchmarks.
+
+## What Kumi does not guarantee 
+
+Lambdas (e.g. -> inside the schema), external IO, floating-point vs bignum, JS transpiler edge cases, time-zone math differences, etc.
+
 ## Learn More
 
 - [DSL Syntax Reference](docs/SYNTAX.md)

data/docs/AST.md

@@ -77,7 +77,7 @@ CaseExpression = Struct.new(:condition, :result)
 ```
 
 **Case type mappings**:
-- `on :a, :b, result` → `condition: fn(:all?, ref(:a), ref(:b))`  
+- `on :a, :b, result` → `condition: fn(:cascade_and, ref(:a), ref(:b))`  
 - `on_any :a, :b, result` → `condition: fn(:any?, ref(:a), ref(:b))`
 - `base result` → `condition: literal(true)`
 

data/docs/FUNCTIONS.md

@@ -10,6 +10,8 @@ Kumi provides a rich library of built-in functions for use within `value` and `t
   * **Usage**: `fn(:and, boolean1, boolean2, ...)` → `boolean`
 * **`any?`**: Check if any element in collection is truthy
   * **Usage**: `fn(:any?, array(any) arg1)` → `boolean`
+* **`cascade_and`**: Element-wise AND for arrays with same nested structure
+  * **Usage**: `fn(:cascade_and, boolean1, boolean2, ...)` → `boolean`
 * **`none?`**: Check if no elements in collection are truthy
   * **Usage**: `fn(:none?, array(any) arg1)` → `boolean`
 * **`not`**: Logical NOT
@@ -52,14 +54,14 @@ Kumi provides a rich library of built-in functions for use within `value` and `t
   * **Usage**: `fn(:modulo, float arg1, float arg2)` → `float`
 * **`multiply`**: Multiply two numbers
   * **Usage**: `fn(:multiply, float arg1, float arg2)` → `float`
+* **`piecewise_sum`**: Accumulate over tiered ranges; returns [sum, marginal_rate]
+  * **Usage**: `fn(:piecewise_sum, float arg1, array(float) arg2, array(float) arg3)` → `array(float)`
 * **`power`**: Raise first number to power of second
   * **Usage**: `fn(:power, float arg1, float arg2)` → `float`
 * **`round`**: Round number to specified precision
   * **Usage**: `fn(:round, float1, float2, ...)` → `float`
 * **`subtract`**: Subtract second number from first
   * **Usage**: `fn(:subtract, float arg1, float arg2)` → `float`
-* **`piecewise_sum`**: Accumulate over tiered ranges; returns [sum, marginal_rate]
-  * **Usage**: `fn(:piecewise_sum, float arg1, array(float) arg2, array(float) arg3)` → `array(float)`
 
 ## String Functions
 
@@ -67,16 +69,22 @@ Kumi provides a rich library of built-in functions for use within `value` and `t
   * **Usage**: `fn(:capitalize, string arg1)` → `string`
 * **`concat`**: Concatenate multiple strings
   * **Usage**: `fn(:concat, string1, string2, ...)` → `string`
+* **`contains?`**: Check if string contains substring
+  * **Usage**: `fn(:contains?, string arg1, string arg2)` → `boolean`
 * **`downcase`**: Convert string to lowercase
   * **Usage**: `fn(:downcase, string arg1)` → `string`
 * **`end_with?`**: Check if string ends with suffix
   * **Usage**: `fn(:end_with?, string arg1, string arg2)` → `boolean`
-* **`include?`**: Check if collection includes element
-  * **Usage**: `fn(:include?, array(any) arg1, any arg2)` → `boolean`
-* **`length`**: Get collection length
-  * **Usage**: `fn(:length, array(any) arg1)` → `integer`
+* **`includes?`**: Check if string contains substring
+  * **Usage**: `fn(:includes?, string arg1, string arg2)` → `boolean`
+* **`length`**: Get string length
+  * **Usage**: `fn(:length, string arg1)` → `integer`
 * **`start_with?`**: Check if string starts with prefix
   * **Usage**: `fn(:start_with?, string arg1, string arg2)` → `boolean`
+* **`string_include?`**: Check if string contains substring
+  * **Usage**: `fn(:string_include?, string arg1, string arg2)` → `boolean`
+* **`string_length`**: Get string length
+  * **Usage**: `fn(:string_length, string arg1)` → `integer`
 * **`strip`**: Remove leading and trailing whitespace
   * **Usage**: `fn(:strip, string arg1)` → `string`
 * **`upcase`**: Convert string to uppercase
@@ -84,20 +92,54 @@ Kumi provides a rich library of built-in functions for use within `value` and `t
 
 ## Collection Functions
 
+* **`all_across`**: Check if all elements are truthy across all nested levels
+  * **Usage**: `fn(:all_across, array(any) arg1)` → `boolean`
+* **`any_across`**: Check if any element is truthy across all nested levels
+  * **Usage**: `fn(:any_across, array(any) arg1)` → `boolean`
+* **`avg_if`**: Average values where corresponding condition is true
+  * **Usage**: `fn(:avg_if, array(float) arg1, array(boolean) arg2)` → `float`
+* **`build_array`**: Build array of given size with index values
+  * **Usage**: `fn(:build_array, integer arg1)` → `array(any)`
+* **`count_across`**: Count total elements across all nested levels
+  * **Usage**: `fn(:count_across, array(any) arg1)` → `integer`
+* **`count_if`**: Count number of true values in boolean array
+  * **Usage**: `fn(:count_if, array(boolean) arg1)` → `integer`
+* **`each_slice`**: Group array elements into subarrays of given size
+  * **Usage**: `fn(:each_slice, array arg1, integer arg2)` → `array(array)`
 * **`empty?`**: Check if collection is empty
   * **Usage**: `fn(:empty?, array(any) arg1)` → `boolean`
 * **`first`**: Get first element of collection
   * **Usage**: `fn(:first, array(any) arg1)` → `any`
+* **`flatten`**: Flatten nested arrays into a single array
+  * **Usage**: `fn(:flatten, array(any) arg1)` → `array(any)`
+* **`flatten_deep`**: Recursively flatten all nested arrays (alias for flatten)
+  * **Usage**: `fn(:flatten_deep, array(any) arg1)` → `array(any)`
+* **`flatten_one`**: Flatten nested arrays by one level only
+  * **Usage**: `fn(:flatten_one, array(any) arg1)` → `array(any)`
 * **`include?`**: Check if collection includes element
   * **Usage**: `fn(:include?, array(any) arg1, any arg2)` → `boolean`
+* **`indices`**: Generate array of indices for the collection
+  * **Usage**: `fn(:indices, array(any) arg1)` → `array(integer)`
+* **`join`**: Join array elements into string with separator
+  * **Usage**: `fn(:join, array arg1, string arg2)` → `string`
 * **`last`**: Get last element of collection
   * **Usage**: `fn(:last, array(any) arg1)` → `any`
-* **`length`**: Get collection length
-  * **Usage**: `fn(:length, array(any) arg1)` → `integer`
+* **`map_add`**: Add value to each element
+  * **Usage**: `fn(:map_add, array(float) arg1, float arg2)` → `array(float)`
+* **`map_conditional`**: Transform elements based on condition: if element == condition_value then true_value else false_value
+  * **Usage**: `fn(:map_conditional, array arg1, any arg2, any arg3, any arg4)` → `array`
+* **`map_join_rows`**: Join 2D array into string with row and column separators
+  * **Usage**: `fn(:map_join_rows, array(array) arg1, string arg2, string arg3)` → `string`
+* **`map_multiply`**: Multiply each element by factor
+  * **Usage**: `fn(:map_multiply, array(float) arg1, float arg2)` → `array(float)`
+* **`map_with_index`**: Map collection elements to [element, index] pairs
+  * **Usage**: `fn(:map_with_index, array(any) arg1)` → `array(any)`
 * **`max`**: Find maximum value in numeric collection
   * **Usage**: `fn(:max, array(float) arg1)` → `float`
 * **`min`**: Find minimum value in numeric collection
   * **Usage**: `fn(:min, array(float) arg1)` → `float`
+* **`range`**: Generate range of integers from start to finish (exclusive)
+  * **Usage**: `fn(:range, integer arg1, integer arg2)` → `array(integer)`
 * **`reverse`**: Reverse collection order
   * **Usage**: `fn(:reverse, array(any) arg1)` → `array(any)`
 * **`size`**: Get collection size
@@ -106,6 +148,8 @@ Kumi provides a rich library of built-in functions for use within `value` and `t
   * **Usage**: `fn(:sort, array(any) arg1)` → `array(any)`
 * **`sum`**: Sum all numeric elements in collection
   * **Usage**: `fn(:sum, array(float) arg1)` → `float`
+* **`sum_if`**: Sum values where corresponding condition is true
+  * **Usage**: `fn(:sum_if, array(float) arg1, array(boolean) arg2)` → `float`
 * **`unique`**: Remove duplicate elements from collection
   * **Usage**: `fn(:unique, array(any) arg1)` → `array(any)`