kumi 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243e6f2e2f7f65919f41fae1eddf877796e6221674e41dc5d32a36c708efab03
-  data.tar.gz: 8649def0a1299dd416d00480daa9fb0dfe3b6e418c4ea6c1ad869c873ad3eedf
+  metadata.gz: 91e6e3b6ce1e4911d37588ba8aaf9b89f8129d23fe93b05268756c417249da90
+  data.tar.gz: f019de05a9e05957184fc649d187306fa7cd3736cb9d04c56d6080d4a3cde9de
 SHA512:
-  metadata.gz: e677d95d1ef34f8144b1f829259ad716e8f3822ab216957cf34a0058b4f7651843232202dc485a62e4c44077761a91b4db419963b649fae4a429042bf49be410
-  data.tar.gz: 3e7795238333d362f35c71b9478b01f4ff396110dc517a320dc304288a1ab8deac0a3af8b99c3d8f87cfd47a9a91f1bbd46509eb0055db4faa042b9b6ca14bd9
+  metadata.gz: 6d6439258bcb876374c5f7ca3bafa4e59faabf112e3cfe2dac532f752b2b7ef8533bf888c4e6feb1509995069a103a258b37c6b18b0164487e5215e03dd85b10
+  data.tar.gz: 6e64f9725569836d7a17b83aa82f316f01d4a9169a1323cee3d1d5fcf7d3782902b9c0695bcdb3735a4c206906463a4b7ca3e14f39f253ba23bf23d572ce95aa

data/CLAUDE.md

@@ -3,6 +3,7 @@
 !! Remember, this gem is not on production yet, so no backward compatilibity is necessary. But do not change the public interfaces (e.g. DSL, Schema) without explicitly requested or demanded. 
 !! We are using zeitwerk, i.e.: no requires
 !! Do not care about linter or coverage unless asked to do so.
+!! IMPORTANT: Communication style - Write direct, factual statements. Avoid promotional language, unnecessary claims, or marketing speak. State what the system does, not what benefits it provides. Use TODOs for missing information rather than placeholder claims.
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
@@ -27,6 +28,19 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `gem build kumi.gemspec` - Build the gem
 - `gem install ./kumi-*.gem` - Install locally built gem
 
+### Kumi CLI
+- `./bin/kumi -i` - Start interactive REPL mode for rapid schema testing
+- `./bin/kumi -f schema.rb -d data.json` - Execute schema file with input data
+- `./bin/kumi -f schema.rb -k key1,key2` - Extract specific keys from schema
+- `./bin/kumi -f schema.rb -e key_name` - Explain how a key is computed
+- `./bin/kumi -f schema.rb -d data.json -o json` - Output results in JSON format
+
+**CLI Features**:
+- Interactive REPL with schema loading, data manipulation, and live evaluation
+- File-based schema execution with JSON/YAML input data support
+- Selective key extraction and explain functionality for debugging
+- Multiple output formats (pretty, JSON, YAML) for integration
+
 ## Architecture Overview
 
 ### Core Components
@@ -47,9 +61,17 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 **Syntax Tree** (`lib/kumi/syntax/`):
 - `node.rb` - Base node class with location tracking
 - `root.rb` - Root schema node containing inputs, attributes, and traits
-- `declarations.rb` - Attribute and trait declaration nodes  
-- `expressions.rb` - Expression nodes (calls, lists, cascades)
-- `terminal_expressions.rb` - Terminal nodes (literals, field references, bindings, field declarations)
+- `value_declaration.rb` - Value declaration nodes (formerly Attribute)
+- `trait_declaration.rb` - Trait declaration nodes (formerly Trait)
+- `input_declaration.rb` - Input field declaration nodes (formerly FieldDecl)
+- `call_expression.rb` - Function call expression nodes
+- `array_expression.rb` - Array expression nodes (formerly ListExpression)
+- `hash_expression.rb` - Hash expression nodes (for future hash literals)
+- `cascade_expression.rb` - Cascade expression nodes (conditional values)
+- `case_expression.rb` - Case expression nodes (formerly WhenCaseExpression)
+- `literal.rb` - Literal value nodes
+- `input_reference.rb` - Input field reference nodes (formerly FieldRef)  
+- `declaration_reference.rb` - Declaration reference nodes (formerly Binding)
 
 **Analyzer** (`lib/kumi/analyzer.rb`):
 - Multi-pass analysis system that validates schemas and builds dependency graphs
@@ -91,6 +113,58 @@ Kumi is a declarative decision-modeling compiler for Ruby that transforms comple
 - `domain/enum_analyzer.rb` - Enumeration domain analysis and validation
 - `domain/violation_formatter.rb` - Formats domain violation error messages
 
+## DSL Syntax Requirements
+
+### Critical Syntax Rules
+
+**Module Definition Structure** (REQUIRED for CLI):
+```ruby
+# CORRECT - CLI can find and load this
+module SchemaName
+  extend Kumi::Schema
+  
+  schema do
+    # schema definition here
+  end
+end
+
+# INCORRECT - CLI cannot load standalone schemas
+schema do  # This won't work with CLI
+  # schema definition
+end
+```
+
+**Function Call Syntax**:
+- **Symbol style**: `fn(:function_name, arg1, arg2)` - Always works, explicit
+- **Method style**: `fn.function_name(arg1, arg2)` - Also works, more readable
+- **Incorrect**: `fn()` - Empty function calls cause parse errors
+- **Incorrect**: `fn.function_name()` - Empty method calls cause parse errors
+
+**Arithmetic Operations**:
+- **Sugar Syntax**: `input.field1 + input.field2` - Works for input fields and value references
+- **Function Syntax**: `fn(:add, input.field1, input.field2)` - Always works, more explicit
+- **Mixed**: Use sugar for simple operations, functions for complex ones
+
+**Cascade Condition Syntax**:
+```ruby
+# CORRECT - use symbols for trait references in cascades
+value :status do
+  on trait_name, "Result"
+  base "Default"
+end
+
+# INCORRECT - bare identifiers don't work in cascade conditions
+value :status do
+  on trait_name, "Result"  # This will fail
+  base "Default"
+end
+```
+
+**UnsatDetector Considerations**:
+- Cascades with mutually exclusive conditions are valid (e.g., `amount < 100` vs `amount >= 100`)
+- Values that depend on such cascades are also valid (fixed in recent update)
+- Use clear, non-contradictory trait names to avoid confusion
+
 ### Key Patterns
 
 **DSL Structure**:
@@ -120,8 +194,8 @@ end
 In cascade expressions (`value :name do ... end`), trait references use **symbols**, not bare identifiers:
 ```ruby
 value :status do
-  on :adult, "Adult Status"      # ✅ Correct - use :trait_name symbol
-  on :verified, "Verified User"
+  on adult, "Adult Status"      # ✅ Correct - use trait_name symbol
+  on verified, "Verified User"
   base "Unverified"
 end
 
@@ -170,6 +244,7 @@ end
 The `examples/` directory contains comprehensive examples showing Kumi usage patterns:
 - `cascade_demonstration.rb` - Demonstrates cascade logic with UnsatDetector fixes (working)
 - `working_comprehensive_schema.rb` - Complete feature showcase (current best practices, working)
+- Mathematical predicate examples - Safe mutual recursion patterns using cascade mutual exclusion
 - `federal_tax_calculator_2024.rb` - Real-world tax calculation example (working)
 - `tax_2024.rb` - Simple tax example with explain functionality (working)
 - `wide_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for wide schemas (compilation and evaluation scaling)
@@ -196,9 +271,53 @@ The `examples/` directory contains comprehensive examples showing Kumi usage pat
 7. `lib/kumi/analyzer/passes/type_checker.rb` - Type validation with enhanced error messages
 8. `spec/kumi/input_block_spec.rb` - Input block syntax and behavior
 9. `spec/integration/compiler_integration_spec.rb` - End-to-end test examples
-10. `documents/DSL.md` - Concise DSL syntax reference
-11. `documents/AST.md` - AST node types and structure reference
-12. `documents/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
+10. `docs/DSL.md` - Concise DSL syntax reference
+11. `docs/AST.md` - AST node types and structure reference
+12. `docs/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
+13. `lib/kumi/cli.rb` - CLI implementation with REPL and file execution
+14. `examples/simple_tax_schema.rb` - CLI-compatible schema example
+15. `docs/features/analysis-cascade-mutual-exclusion.md` - Cascade mutual exclusion detection feature documentation
+16. `docs/features/array-broadcasting.md` - Array broadcasting and vectorization system documentation
+
+## CLI Usage and Best Practices
+
+### Schema File Requirements
+- **Must use module structure**: `module SchemaName; extend Kumi::Schema; schema do ... end; end`
+- **Must have proper require**: `require_relative "../lib/kumi"` at the top
+- **Must have input block**: Even empty `input {}` blocks are required
+- **Avoid inline definitions**: Don't define schemas directly in methods or blocks
+
+### CLI Development Workflow
+1. **Start with REPL**: Use `./bin/kumi -i` for rapid prototyping and testing
+2. **Test with files**: Create `.rb` schema files and `.json/.yaml` data files
+3. **Iterate quickly**: Use `-k key1,key2` to focus on specific outputs
+4. **Debug with explain**: Use `-e key_name` to understand computation flow
+5. **Validate with different data**: Test edge cases with varied input data
+
+### Common CLI Patterns
+```bash
+# Interactive development
+./bin/kumi -i
+kumi> schema examples/my_schema.rb
+kumi> data test_data.json
+kumi> get result
+
+# File-based execution
+./bin/kumi -f examples/tax_schema.rb -d examples/tax_data.json -k total_tax,effective_rate
+
+# Debugging computations
+./bin/kumi -f examples/complex_schema.rb -d examples/data.json -e complex_calculation
+
+# Output formats for integration
+./bin/kumi -f schema.rb -d data.json -k results -o json | jq '.results'
+```
+
+### Troubleshooting Schema Issues
+- **Parse Errors**: Check function syntax (avoid empty `fn()` calls)
+- **Module Not Found**: Ensure proper module structure and naming
+- **UnsatDetector Errors**: Review trait logic for contradictions
+- **Type Errors**: Check input block type declarations match usage
+- **Runtime Errors**: Use explain to trace computation dependencies
 
 ## Input Block System Details
 
@@ -239,6 +358,39 @@ input do
 end
 ```
 
+### Array Broadcasting System
+
+**Automatic Vectorization**: Field access on array inputs (`input.items.price`) applies operations element-wise with intelligent map/reduce detection.
+
+**Basic Broadcasting**:
+```ruby
+input do
+  array :line_items do
+    float   :price
+    integer :quantity  
+    string  :category
+  end
+end
+
+# Element-wise computation - broadcasts over each item
+value :subtotals, input.line_items.price * input.line_items.quantity
+trait :is_taxable, (input.line_items.category != "digital")
+```
+
+**Aggregation Operations**: Functions consuming arrays automatically detected:
+```ruby
+value :total_subtotal, fn(:sum, subtotals)
+value :avg_price, fn(:avg, input.line_items.price)
+value :max_quantity, fn(:max, input.line_items.quantity)
+```
+
+**Implementation Components**:
+- **InputElementReference** AST nodes for nested field access paths
+- **BroadcastDetector** analyzer pass identifies vectorized vs scalar operations  
+- **Compiler** generates appropriate map/reduce functions based on usage context
+- **Type Inference** automatically infers types for array element operations
+- Supports arbitrary depth field access with nested arrays and hashes
+
 ### Trait Syntax Evolution
 
 **Current Syntax** (recommended):